fixeria submitted this change.

View Change

[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(-)

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

To view, visit change 41096. To unsubscribe, or for help writing mail filters, visit settings.