diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..8b5c6187184da2b5d0401d5129544f6782540f3c --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +protoc/ +go-stubs/ +ruby-stubs/ +.proto-gen/ +python-stubs/ +.vscode/ \ No newline at end of file diff --git a/README.md b/README.md index 24c09df5ed7719d576d4b9fc71e37ffb8ae1d5ed..d905b73d80bddbbe901f882b36df8026fbae57e8 100644 --- a/README.md +++ b/README.md @@ -3,13 +3,13 @@ This repository contains OpenAPIs descriptions for the interfaces specified in ETSI GS MEC 014. ## Online resources -* [Specification Document](https://www.etsi.org/deliver/etsi_gs/MEC/001_099/014/02.01.01_60/gs_MEC014v020101p.pdf) +* [Specification Document](https://www.etsi.org/deliver/etsi_gs/MEC/001_099/014/03.01.01_60/gs_MEC014v030101p.pdf) ## Navigate with Swagger UI -* [UE Identity API](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/mec/gs014-ue-identity-api/raw/master/UEidentityAPI.yaml) +* [UE Identity API](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/mec/gs014-ue-identity-api/raw/stf644/UEidentityAPI.yaml) ## Navigate with redocly -* [UE Identity API](https://redocly.github.io/redoc/?url=https://forge.etsi.org/rep/mec/gs014-ue-identity-api/raw/master/UEidentityAPI.yaml&nocors) +* [UE Identity API](https://redocly.github.io/redoc/?url=https://forge.etsi.org/rep/mec/gs014-ue-identity-api/raw/stf644/UEidentityAPI.yaml&nocors) ## License diff --git a/UEidentityAPI.json b/UEidentityAPI.json index 780123e8c7c151a9bf4997e9c481ee330f22f6d5..3422b2b2b1dde675ee301f8d7a1a9cee111691a1 100644 --- a/UEidentityAPI.json +++ b/UEidentityAPI.json @@ -2,7 +2,7 @@ "openapi": "3.1.0", "info": { "title": "UE Identity API", - "version": "2.1.1", + "version": "3.1.1", "description": "The ETSI MEC ISG MEC014 UE Identity API described using OpenAPI", "license": { "name": "BSD-3-Clause", @@ -13,8 +13,8 @@ } }, "externalDocs": { - "description": "ETSI GS MEC014 UE Identity API, V2.1.1", - "url": "http://www.etsi.org/deliver/etsi_gs/MEC/001_099/014/02.01.01_60/gs_mec014v020101p.pdf" + "description": "ETSI GS MEC014 UE Identity API, V3.1.1", + "url": "http://www.etsi.org/deliver/etsi_gs/MEC/001_099/014/03.01.01_60/gs_mec014v030101p.pdf" }, "security": [{ "OauthSecurity": [ diff --git a/UEidentityAPI.yaml b/UEidentityAPI.yaml index 923b5031f63246982c9144777c64ca49f9bfd41f..b7241bf054eb6b49c33897c62554b4392cee1825 100644 --- a/UEidentityAPI.yaml +++ b/UEidentityAPI.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: UE Identity API - version: 2.1.1 + version: 3.1.1 description: The ETSI MEC ISG MEC014 UE Identity API described using OpenAPI license: name: BSD-3-Clause @@ -9,8 +9,8 @@ info: contact: email: cti_support@etsi.org externalDocs: - description: ETSI GS MEC014 UE Identity API, V2.1.1 - url: http://www.etsi.org/deliver/etsi_gs/MEC/001_099/014/02.01.01_60/gs_mec014v020101p.pdf + description: ETSI GS MEC014 UE Identity API, V3.1.1 + url: http://www.etsi.org/deliver/etsi_gs/MEC/001_099/014/03.01.01_60/gs_mec014v030101p.pdf security: - OauthSecurity: - all diff --git a/proto3-gen.md b/proto3-gen.md new file mode 100644 index 0000000000000000000000000000000000000000..5558270ed3e6a7e01dc07eb1914a129b3fd68c7c --- /dev/null +++ b/proto3-gen.md @@ -0,0 +1,134 @@ +# Protobuf Schema Generation + +[OpenAPI Generator](https://openapi-generator.tech) is used to generate protobuf schema (`.proto3`) files from OpenAPI specifications of MEC014 UE-Identity API. + +>**NOTE:** At the time of writing, the tool does not support OAS 3.1 version and we have to first convert the [IoT API](./UEidentityAPI.yaml) to OAS 3.0 for generating protobuf schema. + +1. Convert OAS for [IoT API](./UEidentityAPI.yaml) from 3.1 to 3.0​ + + - Change the value of `openapi` field from 3.1.0 to 3.0.0​ + + - Use this [VS code extension](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) to see the errors in the downgraded YAML (v3.0)​ + + - Manually fix the errors​ + - mostly related to `examples` <--> `example` interchange​ + - or some 3.1 fields that are not supported in 3.0​ (comment them out) + +2. Generate proto files + - Install the `openapi-generator-cli.jar` using the installation procedure mentioned [here](https://openapi-generator.tech/docs/installation#jar). + - Generate the proto files using the following command + ```sh + $ java -jar openapi-generator-cli.jar generate -i UEidentityAPI.yaml -g protobuf-schema -o proto3/ --package-name mec014 + ``` + +3. Carefully inspect the generated `.proto` files for any inconsistencies. Some of the things to look out for: + - Proto3 generated files for enumerations, structures containing allOf, oneOf, anyOf etc. may need to be touched manually + - Check that all the nested models are being _imported_ correctly in their parent models + - Remove redundant proto files + + +4. Validate protobuf schema by generating code from proto3 descriptions in different languages. See [this section](#code-generation-from-proto3) for more details. + +# Code Generation from proto3 + +Below are some code generation examples for Python, Go and Ruby. For other languages, please refer to https://grpc.io/docs/quickstart/. + +### Python + +Below are some code generation examples for Python, Go and Ruby. For other languages, please refer to https://grpc.io/docs/quickstart/. + +### Python + +1. Install the grpcio-tools package + ```sh + $ pip install grpcio-tools + ``` + +2. Create a directory for generated Python stubs + ```sh + $ mkdir python-stubs + ``` + +3. Run the following commands from the root of the directory containing this README that you are reading. + + - Models: + + ```sh + $ python -m grpc_tools.protoc -I./proto3 --python_out=./python-stubs ./proto3/models/* + ``` + + The above command will generate .py files for all the data models in the ./models directory + + - Services: + + ```sh + $ python -m grpc_tools.protoc -I./proto3 --python_out=./python-stubs --grpc_python_out=./python-stubs ./proto3/services/ue_identity_tag_info_service.proto + ``` + + The above command will generate two files for the IoT service: + - ue_identity_tag_info_service_pb2.py: containing the python data models used in the identity service file + - ue_identity_tag_info_service_pb2_grpc.py: containing all the classes and functions needed for the supported HTTP methods in the UE-IDENTITY-API + +### Go + +1. Install protocol buffer compiler + ```sh + $ apt install -y protobuf-compiler + ``` +2. Install Go plugins for `protoc` + ```sh + $ go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28.1 + ``` + ```sh + $ go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2.0 + ``` +3. Update `PATH` so `protoc` can find the plugins + ```sh + $ export PATH="$PATH:$(go env GOPATH)/bin" + ``` +4. Define a go package by appending `option go_package = "./mec014.services.Identityservice";` in all .proto files like this: + + ```Go + ... + + syntax = "proto3"; + + package mec014.services.Identityservice; + + option go_package = "./mec014.services.Identityservice"; + + import public "models/.proto"; + + ... + ``` +5. Generate Go code for models and services + ```sh + $ mkdir go-stubs + $ protoc --go_out=./go-stubs ./proto3/models/* -I./proto3 + $ protoc --go_out=./go-stubs ./proto3/services/* --go-grpc_out=go-stubs -I./proto3 + ``` + > The generated `.pb.go` files will contain all the protocol buffer code to populate, serialize, and retrieve request and response message types defined in the `models` folder. + > And the `ue_identity_tag_info_service_grpc.pb.go` will contain the stubs for the methods defined in the `ue_identity_tag_info_service.proto` file. + +### Ruby + +1. Install gRPC Ruby Plugin and required tools + ```sh + $ gem install grpc + $ sudo apt install ruby-grpc-tools + ``` + +2. Generate code + ```sh + $ mkdir ruby-stubs + ``` + + Run the following command to create Ruby modules for all the data models defined in the proto files. + + ```sh + $ grpc_tools_ruby_protoc -I./proto3 --ruby_out=ruby-stubs ./proto3/models/* + ``` + Run the following command to generate `ue_identity_tag_info_service_pb2` and `ue_identity_tag_info_service_pb2_grpc` files, containing stub and service classes for the endpoints and methods defined in MEC014 UE-Identity service. + + ```sh + $ grpc_tools_ruby_protoc -I./proto3 --ruby_out=ruby-stubs --grpc_out=ruby-stubs ./proto3/services/* diff --git a/proto3/.openapi-generator-ignore b/proto3/.openapi-generator-ignore new file mode 100644 index 0000000000000000000000000000000000000000..7484ee590a3894506cf063799b885428f95a71be --- /dev/null +++ b/proto3/.openapi-generator-ignore @@ -0,0 +1,23 @@ +# OpenAPI Generator Ignore +# Generated by openapi-generator https://github.com/openapitools/openapi-generator + +# Use this file to prevent files from being overwritten by the generator. +# The patterns follow closely to .gitignore or .dockerignore. + +# As an example, the C# client generator defines ApiClient.cs. +# You can make changes and tell OpenAPI Generator to ignore just this file by uncommenting the following line: +#ApiClient.cs + +# You can match any string of characters against a directory, file or extension with a single asterisk (*): +#foo/*/qux +# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux + +# You can recursively match patterns against a directory, file or extension with a double asterisk (**): +#foo/**/qux +# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux + +# You can also negate patterns with an exclamation (!). +# For example, you can ignore all files in a docs folder with the file extension .md: +#docs/*.md +# Then explicitly reverse the ignore rule for a single file: +#!docs/README.md diff --git a/proto3/.openapi-generator/FILES b/proto3/.openapi-generator/FILES new file mode 100644 index 0000000000000000000000000000000000000000..106c0c29f0c2c7f8c343561ec14ce0412575890e --- /dev/null +++ b/proto3/.openapi-generator/FILES @@ -0,0 +1,6 @@ +.openapi-generator-ignore +README.md +models/problem_details.proto +models/state.proto +models/ue_identity_tag_info.proto +services/ue_identity_tag_info_service.proto diff --git a/proto3/.openapi-generator/VERSION b/proto3/.openapi-generator/VERSION new file mode 100644 index 0000000000000000000000000000000000000000..1e20ec35c6422c05be73f5929fbac4c67c304fd2 --- /dev/null +++ b/proto3/.openapi-generator/VERSION @@ -0,0 +1 @@ +5.4.0 \ No newline at end of file diff --git a/proto3/README.md b/proto3/README.md new file mode 100644 index 0000000000000000000000000000000000000000..7cfe760985f9dce906a00266d0c736bdd83952ee --- /dev/null +++ b/proto3/README.md @@ -0,0 +1,110 @@ +# gPRC for mec014 + +The ETSI MEC ISG MEC014 UE Identity API described using OpenAPI + +## Overview +These files were generated by the [OpenAPI Generator](https://openapi-generator.tech) project. + +- API version: 3.1.1 +- Package version: +- Build package: org.openapitools.codegen.languages.ProtobufSchemaCodegen + +## Usage + +Below are some code generation examples for Python, Go and Ruby. For other languages, please refer to https://grpc.io/docs/quickstart/. + +### Python + +1. Install the grpcio-tools package + ```sh + $ pip install grpcio-tools + ``` + +2. Create a directory for generated Python stubs + ```sh + $ mkdir python-stubs + ``` + +3. Run the following commands from the root of the directory containing this README that you are reading. + + - Models: + + ```sh + $ python -m grpc_tools.protoc -I./proto3 --python_out=./python-stubs ./proto3/models/* + ``` + + The above command will generate .py files for all the data models in the ./models directory + + - Services: + + ```sh + $ python -m grpc_tools.protoc -I./proto3 --python_out=./python-stubs --grpc_python_out=./python-stubs ./proto3/services/ue_identity_tag_info_service.proto + ``` + + The above command will generate two files for the IoT service: + - ue_identity_tag_info_service_pb2.py: containing the python data models used in the identity service file + - ue_identity_tag_info_service_pb2_grpc.py: containing all the classes and functions needed for the supported HTTP methods in the UE-IDENTITY-API + +### Go + +1. Install protocol buffer compiler + ```sh + $ apt install -y protobuf-compiler + ``` +2. Install Go plugins for `protoc` + ```sh + $ go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28.1 + ``` + ```sh + $ go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2.0 + ``` +3. Update `PATH` so `protoc` can find the plugins + ```sh + $ export PATH="$PATH:$(go env GOPATH)/bin" + ``` +4. Define a go package by appending `option go_package = "./mec014.services.Identityservice";` in all .proto files like this: + + ```Go + ... + + syntax = "proto3"; + + package mec014.services.Identityservice; + + option go_package = "./mec014.services.Identityservice"; + + import public "models/.proto"; + + ... + ``` +5. Generate Go code for models and services + ```sh + $ mkdir go-stubs + $ protoc --go_out=./go-stubs ./proto3/models/* -I./proto3 + $ protoc --go_out=./go-stubs ./proto3/services/* --go-grpc_out=go-stubs -I./proto3 + ``` + > The generated `.pb.go` files will contain all the protocol buffer code to populate, serialize, and retrieve request and response message types defined in the `models` folder. + > And the `ue_identity_tag_info_service_grpc.pb.go` will contain the stubs for the methods defined in the `ue_identity_tag_info_service.proto` file. + +### Ruby + +1. Install gRPC Ruby Plugin and required tools + ```sh + $ gem install grpc + $ sudo apt install ruby-grpc-tools + ``` + +2. Generate code + ```sh + $ mkdir ruby-stubs + ``` + + Run the following command to create Ruby modules for all the data models defined in the proto files. + + ```sh + $ grpc_tools_ruby_protoc -I./proto3 --ruby_out=ruby-stubs ./proto3/models/* + ``` + Run the following command to generate `ue_identity_tag_info_service_pb2` and `ue_identity_tag_info_service_pb2_grpc` files, containing stub and service classes for the endpoints and methods defined in MEC014 UE-Identity service. + + ```sh + $ grpc_tools_ruby_protoc -I./proto3 --ruby_out=ruby-stubs --grpc_out=ruby-stubs ./proto3/services/* diff --git a/proto3/models/problem_details.proto b/proto3/models/problem_details.proto new file mode 100644 index 0000000000000000000000000000000000000000..91e0eb0333cf131c1c7ed79179381875134f5679 --- /dev/null +++ b/proto3/models/problem_details.proto @@ -0,0 +1,35 @@ +/* + UE Identity API + + The ETSI MEC ISG MEC014 UE Identity API described using OpenAPI + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec014; + + +message ProblemDetails { + + // A URI reference according to IETF RFC 3986 that identifies the problem type + string type = 1; + + // A short, human-readable summary of the problem type + string title = 2; + + // The HTTP status code for this occurrence of the problem + int32 status = 3; + + // A human-readable explanation specific to this occurrence of the problem + string detail = 4; + + // A URI reference that identifies the specific occurrence of the problem + string instance = 5; + +} diff --git a/proto3/models/state.proto b/proto3/models/state.proto new file mode 100644 index 0000000000000000000000000000000000000000..a0178d96ca581707f95eb4dbd705cd20151c287e --- /dev/null +++ b/proto3/models/state.proto @@ -0,0 +1,21 @@ +/* + UE Identity API + + The ETSI MEC ISG MEC014 UE Identity API described using OpenAPI + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec014; + + +enum State { + UNREGISTERED = 0; + REGISTERED = 1; +} diff --git a/proto3/models/ue_identity_tag_info.proto b/proto3/models/ue_identity_tag_info.proto new file mode 100644 index 0000000000000000000000000000000000000000..7d27f291e5098af3dfe73c50f4e85b3c88884140 --- /dev/null +++ b/proto3/models/ue_identity_tag_info.proto @@ -0,0 +1,24 @@ +/* + UE Identity API + + The ETSI MEC ISG MEC014 UE Identity API described using OpenAPI + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec014; + +import public "models/ue_identity_tags.proto"; + +message UeIdentityTagInfo { + + // 1 to N tags presented by a MEC Application instance to a MEC Platform + UeIdentityTags ueIdentityTags = 1; + +} diff --git a/proto3/models/ue_identity_tags.proto b/proto3/models/ue_identity_tags.proto new file mode 100644 index 0000000000000000000000000000000000000000..1c4c9871ae5ff81534de135aeccac2f4459be23a --- /dev/null +++ b/proto3/models/ue_identity_tags.proto @@ -0,0 +1,26 @@ +/* + UE Identity API + + The ETSI MEC ISG MEC014 UE Identity API described using OpenAPI + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec014; + +import public "models/state.proto"; + +message UeIdentityTags { + + // 1 to N tags presented by a MEC Application instance to a MEC Platform + string ueIdentityTag = 2; + + // Specific tag presented by a MEC Application instance to a MEC Platform + State state = 1; +} diff --git a/proto3/services/ue_identity_tag_info_service.proto b/proto3/services/ue_identity_tag_info_service.proto new file mode 100644 index 0000000000000000000000000000000000000000..dee9e551fb2752c19fc8127f2a3e042efdbbcc26 --- /dev/null +++ b/proto3/services/ue_identity_tag_info_service.proto @@ -0,0 +1,42 @@ +/* + UE Identity API + + The ETSI MEC ISG MEC014 UE Identity API described using OpenAPI + + The version of the OpenAPI document: 3.1.1 + + Contact: cti_support@etsi.org + + Generated by OpenAPI Generator: https://openapi-generator.tech +*/ + +syntax = "proto3"; + +package mec014.services.ueidentitytaginfoservice; + +import public "models/problem_details.proto"; +import public "models/ue_identity_tag_info.proto"; + +service UeIdentityTagInfoService { + rpc UeIdentityTagInfoGET (UeIdentityTagInfoGETRequest) returns (UeIdentityTagInfo); + + rpc UeIdentityTagInfoPUT (UeIdentityTagInfoPUTRequest) returns (UeIdentityTagInfo); + +} + +message UeIdentityTagInfoGETRequest { + // Represents a mobile edge application instance + string appInstanceId = 1; + // Represents a UE + repeated string ueIdentityTag = 2; + +} + +message UeIdentityTagInfoPUTRequest { + // Represents a mobile edge application instance + string appInstanceId = 1; + // 'The updated \"state\" for each included UE Identity tag is included in the entity body of the request' + UeIdentityTagInfo ueIdentityTagInfo = 2; + +} +