From 2adba02dd846eaefc17d8c1b71ae21c3895b9183 Mon Sep 17 00:00:00 2001 From: elinuxhenrik Date: Thu, 3 Nov 2022 14:56:40 +0100 Subject: [PATCH] Update documentation Issue-ID: NONRTRIC-813 Signed-off-by: elinuxhenrik Change-Id: Ic06f5976385529c769edd8b6eac58bcd17c1c030 --- capifcore/README.md | 24 ++++++++++++++++++++++-- capifcore/generate.sh | 16 ++++++++++++---- 2 files changed, 34 insertions(+), 6 deletions(-) diff --git a/capifcore/README.md b/capifcore/README.md index 657687f..cba7ff1 100644 --- a/capifcore/README.md +++ b/capifcore/README.md @@ -26,8 +26,11 @@ This product is a Go implementation of the CAPIF Core function, based on the 3GP ## Generation of API code -The CAPIF APIs are generated from the OpenAPI specification provided by 3GPP. The `generate.sh` script downloads the -specifications from 3GPP, fixes them and then generates the APIs. It also generates the mocks needed for unit testing. The specifications are downloaded from the following site; https://www.3gpp.org/ftp/Specs/archive/29_series. To see the APIs in swagger format, see the following link; https://github.com/jdegre/5GC_APIs/tree/Rel-16#common-api-framework-capif. **NOTE!** The documentation in this link is for release 16 of CAPIF, the downloaded specifications are for release 17. +The CAPIF APIs are generated from the OpenAPI specifications provided by 3GPP. The `generate.sh` script downloads the +specifications from 3GPP, fixes them and then generates the APIs. It also generates the mocks needed for unit testing. +The specifications are downloaded from the following site; https://www.3gpp.org/ftp/Specs/archive/29_series. To see +the APIs in swagger format, see the following link; https://github.com/jdegre/5GC_APIs/tree/Rel-16#common-api-framework-capif. +**NOTE!** The documentation in this link is for release 16 of CAPIF, the downloaded specifications are for release 17. To fix the specifications there are three tools: - `commoncollector`, collects type definitions from peripheral specifications to keep down the number of dependencies to @@ -35,12 +38,29 @@ To fix the specifications there are three tools: - `enumfixer`, fixes enumeration definitions so they can be properly generated. - `specificationfixer`, fixes flaws in the specifications so they can be properly generated. All fixes are hard coded. +### Steps to add a new dependency to the commoncollector + +When a dependency to a new specification is introduced in any of the CAPIF specifications, see example below, the following steps should be performed: + +For the CAPIF specification "TS29222_CAPIF_Discover_Service_API" a new dependency like the following has been introduced. +websockNotifConfig: +    $ref: '**TS29122_CommonData.yaml#/components/schemas/WebsockNotifConfig**' + +1. Copy the bold part of the reference and add it to the `definitions.txt` file. This step is not needed if the type is already defined in the file. +2. Look in the `generate.sh` script, between the "" and "" tags, to see if "TS29122_CommonData" + has already been replaced in "TS29222_CAPIF_Discover_Service_API". +3. If it has not been replaced, add a replacement above the "" tag by copying and adapting the two rows above the tag. + ## Build and test To generate mocks manually, run the following command: go generate ./... +**NOTE!** The `helmmanagement` package contains two mocks from the `helm.sh/helm/v3` product. If they need to be +regenerated, their interfaces must be copied into the `helm.go` file and a generation annotation added before running +the generation script. + To build the application, run the following command: go build diff --git a/capifcore/generate.sh b/capifcore/generate.sh index f3cf738..69516b2 100755 --- a/capifcore/generate.sh +++ b/capifcore/generate.sh @@ -52,6 +52,7 @@ jar xvf common29554apidef.zip jar xvf common29571apidef.zip jar xvf common29572apidef.zip +# Remove types that are not used by CAPIF that have dependencies to other specifications. sed -e 'H;x;/^\( *\)\n\1/{s/\n.*//;x;d;}' -e 's/.*//;x;/\CivicAddress/{s/^\( *\).*/ \1/;x;d;}' TS29571_CommonData.yaml >temp.yaml mv temp.yaml TS29571_CommonData.yaml sed -e 'H;x;/^\( *\)\n\1/{s/\n.*//;x;d;}' -e 's/.*//;x;/\ExternalMbsServiceArea/{s/^\( *\).*/ \1/;x;d;}' TS29571_CommonData.yaml >temp.yaml @@ -72,6 +73,8 @@ sed -e 'H;x;/^\( *\)\n\1/{s/\n.*//;x;d;}' -e 's/.*//;x;/\MbsSession/{s/^\( *\). mv temp.yaml TS29571_CommonData.yaml sed -e 'H;x;/^\( *\)\n\1/{s/\n.*//;x;d;}' -e 's/.*//;x;/\SpatialValidityCond/{s/^\( *\).*/ \1/;x;d;}' TS29571_CommonData.yaml >temp.yaml mv temp.yaml TS29571_CommonData.yaml + +# Remove attributes that can not be generated easily. sed '/accessTokenError.*/,+3d' TS29571_CommonData.yaml >temp.yaml mv temp.yaml TS29571_CommonData.yaml sed '/accessTokenRequest.*/,+3d' TS29571_CommonData.yaml >temp.yaml @@ -83,6 +86,8 @@ mv temp.yaml TS29222_CAPIF_Publish_Service_API.yaml sed '64,68d' TS29222_CAPIF_Discover_Service_API.yaml >temp.yaml # Remove parameter preferred-aef-loc since it doesn't follow the OpenApi specification, "The behavior for nested objects and arrays is undefined." mv temp.yaml TS29222_CAPIF_Discover_Service_API.yaml +# Replace references to external specs that are collected to the common spec by the commoncollector +# cat TS29122_CommonData.yaml | sed 's/TS29572_Nlmf_Location/CommonData/g' > temp.yaml mv temp.yaml TS29122_CommonData.yaml cat TS29122_CommonData.yaml | sed 's/TS29554_Npcf_BDTPolicyControl/CommonData/g' > temp.yaml @@ -93,8 +98,6 @@ cat TS29571_CommonData.yaml | sed 's/TS29514_Npcf_PolicyAuthorization/CommonData mv temp.yaml TS29571_CommonData.yaml cat TS29571_CommonData.yaml | sed 's/TS29572_Nlmf_Location/CommonData/g' > temp.yaml mv temp.yaml TS29571_CommonData.yaml -cat TS29571_CommonData.yaml | sed 's/TS29571_CommonData.yaml//g' > temp.yaml # This spec has references to itself that need to be removed -mv temp.yaml TS29571_CommonData.yaml cat TS29222_CAPIF_Publish_Service_API.yaml | sed 's/TS29572_Nlmf_Location/CommonData/g' > temp.yaml mv temp.yaml TS29222_CAPIF_Publish_Service_API.yaml cat TS29222_CAPIF_Routing_Info_API.yaml | sed 's/TS29520_Nnwdaf_EventsSubscription/CommonData/g' > temp.yaml @@ -103,9 +106,11 @@ cat TS29222_CAPIF_Routing_Info_API.yaml | sed 's/TS29510_Nnrf_NFManagement/Commo mv temp.yaml TS29222_CAPIF_Routing_Info_API.yaml cat TS29222_CAPIF_Events_API.yaml | sed 's/TS29523_Npcf_EventExposure/CommonData/g' > temp.yaml mv temp.yaml TS29222_CAPIF_Events_API.yaml +# -go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@v1.10.1 -PATH=$PATH:~/go/bin +# This spec has references to itself that need to be removed +cat TS29571_CommonData.yaml | sed 's/TS29571_CommonData.yaml//g' > temp.yaml +mv temp.yaml TS29571_CommonData.yaml cd $cwd @@ -128,6 +133,9 @@ go build . cd $cwd +go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@v1.10.1 +PATH=$PATH:~/go/bin + echo "Generating TS29122_CommonData" mkdir -p internal/common29122 oapi-codegen --config gogeneratorspecs/common29122/generator_settings.yaml specs/TS29122_CommonData.yaml -- 2.16.6