fixeria has submitted this change. ( https://gerrit.osmocom.org/c/erlang/osmo-s1gw/+/41096?usp=email )
Change subject: [REST] OpenAPI specification skeleton ......................................................................
[REST] OpenAPI specification skeleton
Change-Id: I84e6ef5cc67cd26b11f7bed8510420e43e18c69b Related: SYS#7066 --- M Makefile M README.md A contrib/openapi.yaml A contrib/yaml2json.py M debian/copyright M debian/osmo-s1gw.install A priv/openapi.json 7 files changed, 57 insertions(+), 2 deletions(-)
Approvals: laforge: Looks good to me, but someone else must approve pespin: Looks good to me, approved Jenkins Builder: Verified
diff --git a/Makefile b/Makefile index 6b9267d..a68877f 100644 --- a/Makefile +++ b/Makefile @@ -17,6 +17,10 @@ src/S1AP-%.erl include/S1AP-%.hrl: asn1/S1AP-%.asn rebar3 asn compile
+.PHONY: openapi +priv/openapi.json: contrib/openapi.yaml + contrib/yaml2json.py $^ > $@ + build: $(GEN_FILES) rebar3 compile
diff --git a/README.md b/README.md index e1723e9..3ff2091 100644 --- a/README.md +++ b/README.md @@ -160,3 +160,21 @@ critical | error | warning | notice | info | debug`) * `#{formatter => { ... }` - logging formatting configuration + + +REST interface +-------------- + +OsmoS1GW implements a custom (non-standard) REST interface, primarily intended +for state introspection. The interface is specified using OpenAPI, with the +specification available in [contrib/openapi.yaml](contrib/openapi.yaml). + +The OpenAPI specification is provided in two formats: + +* **YAML** (`contrib/openapi.yaml`) is the primary specification document. +* **JSON** (`priv/openapi.json`) is generated from the YAML using +[contrib/yaml2json.py](contrib/yaml2json.py) and used as input by the +ERF framework for automatic code generation and the request validation. + +> **Note:** Both files must be kept in sync. When making changes to the YAML +document, make sure to update the JSON counterpart by invoking `make openapi`. diff --git a/contrib/openapi.yaml b/contrib/openapi.yaml new file mode 100644 index 0000000..c7f7ec8 --- /dev/null +++ b/contrib/openapi.yaml @@ -0,0 +1,8 @@ +openapi: 3.0.0 +info: + version: '0.1.0' + title: 'OsmoS1GW REST interface' + +paths: + +components: diff --git a/contrib/yaml2json.py b/contrib/yaml2json.py new file mode 100755 index 0000000..1aadeca --- /dev/null +++ b/contrib/yaml2json.py @@ -0,0 +1,13 @@ +#!/usr/bin/env python3 + +# Author: Vadim Yanitskiy vyanitskiy@sysmocom.de +# SPDX-License-Identifier: GPL-3.0-or-later + +import sys +import yaml +import json + +with open(sys.argv[1], 'r') as f: + data = yaml.safe_load(f) + +json.dump(data, sys.stdout, indent=4) diff --git a/debian/copyright b/debian/copyright index d9fcc54..30d897e 100644 --- a/debian/copyright +++ b/debian/copyright @@ -2,9 +2,10 @@ Source: https://gitea.osmocom.org/erlang/osmo-s1gw Upstream-Name: osmo-s1gw
-Files: src/*.erl +Files: debian/* + src/*.erl include/*.hrl - debian/* + contrib/yaml2json.py Copyright: sysmocom - s.f.m.c. GmbH info@sysmocom.de License: AGPL-3.0-or-later
diff --git a/debian/osmo-s1gw.install b/debian/osmo-s1gw.install index b52efe2..9b46af6 100644 --- a/debian/osmo-s1gw.install +++ b/debian/osmo-s1gw.install @@ -2,3 +2,5 @@ usr/lib/osmo-s1gw etc/osmocom/osmo-s1gw.config lib/systemd/system/osmo-s1gw.service +contrib/openapi.yaml usr/share/doc/osmo-s1gw +priv/openapi.json usr/share/doc/osmo-s1gw diff --git a/priv/openapi.json b/priv/openapi.json new file mode 100644 index 0000000..25ff62a --- /dev/null +++ b/priv/openapi.json @@ -0,0 +1,9 @@ +{ + "openapi": "3.0.0", + "info": { + "version": "0.1.0", + "title": "OsmoS1GW REST interface" + }, + "paths": null, + "components": null +} \ No newline at end of file