Commit 756a184a authored by Walter Featherstone's avatar Walter Featherstone
Browse files

Merge branch 'stf606-final' into 'master'

MEC012 v2.2.1 - OAS 3.1

See merge request !9
parents a19228f7 79a154fa
Pipeline #11078 failed with stage
in 0 seconds
protoc/
go-stubs/
ruby-stubs/
.proto-gen/
python-stubs/
\ No newline at end of file
This diff is collapsed.
This diff is collapsed.
# Protobuf Schema Generation
[OpenAPI Generator](https://openapi-generator.tech) is used to generate protobuf schema (`.proto3`) files from OpenAPI specifications of MEC012 RNI API.
>**NOTE:** At the time of writing, the tool does not support OAS 3.1 version and we have to first convert the [RNI API](./RniAPI.yaml) to OAS 3.0 for generating protobuf schema.
1. Convert OAS for [RNI API](./RniAPI.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 RniAPI.yaml -g protobuf-schema -o proto3/ --package-name mec012
```
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
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
$ python3 -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
$ python3 -m grpc_tools.protoc -I./proto3 --python_out=./python-stubs --grpc_python_out=./python-stubs ./proto3/services/rni-service.proto
```
The above command will generate two files for the RNI service:
- _rni_service_pb2.py_: containing the python data models used in the RNI service file
- _rni_service_pb2_grpc.py_: containing all the classes and functions needed for the supported HTTP methods in the RNI 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.26
```
```sh
$ go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.1
```
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 = "./mec012";` in all .proto files like this:
```Go
...
syntax = "proto3";
package mec012;
option go_package = "./mec012";
import public "models/<xyz>.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 `<data_model>.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 `rni_service_grpc.pb.go` will contain the stubs for the methods defined in the `rni_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 `rni_service_pb.rb` and `rni_service_services_pb.rb` files, containing stub and service classes for the endpoints and methods defined in MEC012 RNI service.
```sh
$ grpc_tools_ruby_protoc -I./proto3 --ruby_out=ruby-stubs --grpc_out=ruby-stubs ./proto3/services/*
```
\ No newline at end of file
......@@ -6,7 +6,6 @@ models/ca_reconf_notification_carrier_aggregation_meas_info.proto
models/ca_reconf_notification_secondary_cell_add.proto
models/ca_reconf_subscription.proto
models/ca_reconf_subscription_filter_criteria_assoc.proto
models/ca_reconf_subscription_links.proto
models/cell_change_notification.proto
models/cell_change_notification_temp_ue_id.proto
models/cell_change_subscription.proto
......@@ -20,6 +19,8 @@ models/l2_meas.proto
models/l2_meas_cell_info.proto
models/l2_meas_cell_ue_info.proto
models/link_type.proto
models/links.proto
models/links2.proto
models/meas_quantity_results_nr.proto
models/meas_rep_ue_notification.proto
models/meas_rep_ue_notification_carrier_aggregation_meas_info.proto
......@@ -44,6 +45,7 @@ models/nr_meas_rep_ue_notification_s_cell.proto
models/nr_meas_rep_ue_notification_serv_cell_meas_info.proto
models/nr_meas_rep_ue_subscription.proto
models/nr_meas_rep_ue_subscription_filter_criteria_nr_mrs.proto
models/nrcgi.proto
models/plmn.proto
models/plmn_info.proto
models/problem_details.proto
......@@ -84,7 +86,9 @@ models/s1_bearer_subscription_s1_bearer_subscription_criteria.proto
models/subscription_link_list.proto
models/subscription_link_list_links.proto
models/subscription_link_list_links_subscription.proto
models/test_notification.proto
models/time_stamp.proto
models/trigger.proto
models/trigger_nr.proto
models/websock_notif_config.proto
services/rni_service.proto
5.0.0-beta2
\ No newline at end of file
5.3.0
\ No newline at end of file
......@@ -3,30 +3,112 @@
The ETSI MEC ISG MEC012 Radio Network Information API described using OpenAPI.
## Overview
These files were generated by the [OpenAPI Generator](https://openapi-generator.tech) project.
These files were generated by the [OpenAPI Generator](https://openapi-generator.tech) project.
- API version: 2.1.1
- API version: 2.2.1
- Package version:
- Build package: org.openapitools.codegen.languages.ProtobufSchemaCodegen
For more information, please visit [https://forge.etsi.org/rep/mec/gs012-rnis-api](https://forge.etsi.org/rep/mec/gs012-rnis-api)
## Usage
Below are some usage examples for Go and Ruby. For other languages, please refer to https://grpc.io/docs/quickstart/.
Below are some usage 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
$ python3 -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
$ python3 -m grpc_tools.protoc -I./proto3 --python_out=./python-stubs --grpc_python_out=./python-stubs ./proto3/services/rni-service.proto
```
The above command will generate two files for the RNI service:
- _rni_service_pb2.py_: containing the python data models used in the RNI service file
- _rni_service_pb2_grpc.py_: containing all the classes and functions needed for the supported HTTP methods in the RNI API
### Go
```
# assuming `protoc-gen-go` has been installed with `go get -u github.com/golang/protobuf/protoc-gen-go`
mkdir /var/tmp/go/
protoc --go_out=/var/tmp/go/ services/*
protoc --go_out=/var/tmp/go/ models/*
```
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.26
```
```sh
$ go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.1
```
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 = "./mec012";` in all .proto files like this:
```Go
...
syntax = "proto3";
package mec012;
option go_package = "./mec012";
import public "models/<xyz>.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 `<data_model>.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 `rni_service_grpc.pb.go` will contain the stubs for the methods defined in the `rni_service.proto` file.
### Ruby
```
# assuming `grpc_tools_ruby_protoc` has been installed via `gem install grpc-tools`
RUBY_OUTPUT_DIR="/var/tmp/ruby/mec012"
mkdir $RUBY_OUTPUT_DIR
grpc_tools_ruby_protoc --ruby_out=$RUBY_OUTPUT_DIR --grpc_out=$RUBY_OUTPUT_DIR/lib services/*
grpc_tools_ruby_protoc --ruby_out=$RUBY_OUTPUT_DIR --grpc_out=$RUBY_OUTPUT_DIR/lib models/*
```
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 `rni_service_pb.rb` and `rni_service_services_pb.rb` files, containing stub and service classes for the endpoints and methods defined in MEC012 RNI service.
```sh
$ grpc_tools_ruby_protoc -I./proto3 --ruby_out=ruby-stubs --grpc_out=ruby-stubs ./proto3/services/*
```
\ No newline at end of file
......@@ -3,7 +3,7 @@
The ETSI MEC ISG MEC012 Radio Network Information API described using OpenAPI.
The version of the OpenAPI document: 2.1.1
The version of the OpenAPI document: 2.2.1
Generated by OpenAPI Generator: https://openapi-generator.tech
*/
......
......@@ -3,7 +3,7 @@
The ETSI MEC ISG MEC012 Radio Network Information API described using OpenAPI.
The version of the OpenAPI document: 2.1.1
The version of the OpenAPI document: 2.2.1
Generated by OpenAPI Generator: https://openapi-generator.tech
*/
......@@ -17,6 +17,7 @@ import public "models/ca_reconf_notification_carrier_aggregation_meas_info.proto
import public "models/ca_reconf_notification_secondary_cell_add.proto";
import public "models/ecgi.proto";
import public "models/time_stamp.proto";
import public "models/links2.proto";
message CaReconfNotification {
......@@ -37,4 +38,7 @@ message CaReconfNotification {
TimeStamp timeStamp = 7;
// Links to resources related to this notification.
Links2 _links = 8;
}
......@@ -3,7 +3,7 @@
The ETSI MEC ISG MEC012 Radio Network Information API described using OpenAPI.
The version of the OpenAPI document: 2.1.1
The version of the OpenAPI document: 2.2.1
Generated by OpenAPI Generator: https://openapi-generator.tech
*/
......
......@@ -3,7 +3,7 @@
The ETSI MEC ISG MEC012 Radio Network Information API described using OpenAPI.
The version of the OpenAPI document: 2.1.1
The version of the OpenAPI document: 2.2.1
Generated by OpenAPI Generator: https://openapi-generator.tech
*/
......
......@@ -3,7 +3,7 @@
The ETSI MEC ISG MEC012 Radio Network Information API described using OpenAPI.
The version of the OpenAPI document: 2.1.1
The version of the OpenAPI document: 2.2.1
Generated by OpenAPI Generator: https://openapi-generator.tech
*/
......@@ -13,21 +13,27 @@ syntax = "proto3";
package mec012;
import public "models/ca_reconf_subscription_filter_criteria_assoc.proto";
import public "models/ca_reconf_subscription_links.proto";
import public "models/links.proto";
import public "models/time_stamp.proto";
import public "models/websock_notif_config.proto";
message CaReconfSubscription {
CaReconfSubscriptionLinks Underscorelinks = 1;
Links _links = 1;
// URI selected by the service consumer to receive notifications on the subscribed RNIS information. This shall be included both in the request and in response.
// URI exposed by the client on which to receive notifications via HTTP. See note.
string callbackReference = 2;
TimeStamp expiryDeadline = 3;
CaReconfSubscriptionFilterCriteriaAssoc filterCriteriaAssoc = 4;
WebsockNotifConfig websockNotifConfig = 5;
// Shall be set to TRUE by the service consumer to request a test notification via HTTP on the callbackReference URI, specified in ETSI GS MEC 009 [6], as described in clause 6.12a.
bool requestTestNotification = 6;
// Shall be set to \"CaReconfSubscription\".
string subscriptionType = 5;
string subscriptionType = 7;
}
......@@ -3,7 +3,7 @@
The ETSI MEC ISG MEC012 Radio Network Information API described using OpenAPI.
The version of the OpenAPI document: 2.1.1
The version of the OpenAPI document: 2.2.1
Generated by OpenAPI Generator: https://openapi-generator.tech
*/
......
......@@ -3,7 +3,7 @@
The ETSI MEC ISG MEC012 Radio Network Information API described using OpenAPI.
The version of the OpenAPI document: 2.1.1
The version of the OpenAPI document: 2.2.1
Generated by OpenAPI Generator: https://openapi-generator.tech
*/
......@@ -16,6 +16,7 @@ import public "models/associate_id.proto";
import public "models/cell_change_notification_temp_ue_id.proto";
import public "models/ecgi.proto";
import public "models/time_stamp.proto";
import public "models/links2.proto";
message CellChangeNotification {
......@@ -42,7 +43,10 @@ message CellChangeNotification {
TimeStamp timeStamp = 6;
// E-UTRAN Cell Global Identifier of the target cell. NOTE: Cardinality N is valid only in case of statuses IN_PREPARATION, REJECTED and CANCELLED.
// E-UTRAN Cell Global Identifier of the target cell.
repeated Ecgi trgEcgi = 7;
// Links to resources related to this notification.
Links2 _links = 8;
}
......@@ -3,7 +3,7 @@
The ETSI MEC ISG MEC012 Radio Network Information API described using OpenAPI.
The version of the OpenAPI document: 2.1.1
The version of the OpenAPI document: 2.2.1
Generated by OpenAPI Generator: https://openapi-generator.tech
*/
......
......@@ -3,7 +3,7 @@
The ETSI MEC ISG MEC012 Radio Network Information API described using OpenAPI.
The version of the OpenAPI document: 2.1.1
The version of the OpenAPI document: 2.2.1
Generated by OpenAPI Generator: https://openapi-generator.tech
*/
......@@ -12,15 +12,16 @@ syntax = "proto3";
package mec012;
import public "models/ca_reconf_subscription_links.proto";
import public "models/links.proto";
import public "models/cell_change_subscription_filter_criteria_assoc_ho.proto";
import public "models/time_stamp.proto";
import public "models/websock_notif_config.proto";
message CellChangeSubscription {
CaReconfSubscriptionLinks Underscorelinks = 1;
Links _links = 1;
// URI selected by the service consumerto receive notifications on the subscribed RNIS information. This shall be included both in the request and in response.
// URI exposed by the client on which to receive notifications via HTTP. See note.
string callbackReference = 2;
TimeStamp expiryDeadline = 3;
......@@ -30,4 +31,9 @@ message CellChangeSubscription {
// Shall be set to \"CellChangeSubscription\".
string subscriptionType = 5;
WebsockNotifConfig websockNotifConfig = 6;
// Shall be set to TRUE by the service consumer to request a test notification via HTTP on the callbackReference URI, specified in ETSI GS MEC 009 [6], as described in clause 6.12a.
bool requestTestNotification = 7;
}
......@@ -3,7 +3,7 @@
The ETSI MEC ISG MEC012 Radio Network Information API described using OpenAPI.
The version of the OpenAPI document: 2.1.1
The version of the OpenAPI document: 2.2.1
Generated by OpenAPI Generator: https://openapi-generator.tech
*/
......
......@@ -3,7 +3,7 @@
The ETSI MEC ISG MEC012 Radio Network Information API described using OpenAPI.
The version of the OpenAPI document: 2.1.1
The version of the OpenAPI document: 2.2.1
Generated by OpenAPI Generator: https://openapi-generator.tech
*/
......
/*
ETSI GS MEC 012 - Radio Network Information API
The ETSI MEC ISG MEC012 Radio Network Information API described using OpenAPI.
The version of the OpenAPI document: 2.1.1
The version of the OpenAPI document: 2.2.1
Generated by OpenAPI Generator: https://openapi-generator.tech
*/
......@@ -12,15 +12,17 @@ syntax = "proto3";
package mec012;
import public "models/expiry_notification_links.proto";
import public "models/links2.proto";
import public "models/time_stamp.proto";
message ExpiryNotification {
ExpiryNotificationLinks Underscorelinks = 1;
string notificationType = 1;
Links2 _links = 2;
TimeStamp expiryDeadline = 2;
TimeStamp expiryDeadline = 3;
TimeStamp timeStamp = 3;
TimeStamp timeStamp = 4;
}
......@@ -3,7 +3,7 @@
The ETSI MEC ISG MEC012 Radio Network Information API described using OpenAPI.
The version of the OpenAPI document: 2.1.1
The version of the OpenAPI document: 2.2.1
Generated by OpenAPI Generator: https://openapi-generator.tech
*/
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment