gps-service-geolocation: api descriptionsandbox/benierc/newapis

- yaml file of an api description example
- html file after generation with mkapihtml
- mkapihtml: generate html file from yaml

Change-Id: I0ec5646bd7ce7fff6d0a0ad5713aca140c01f4eb
Signed-off-by: Clément Bénier <clement.benier@iot.bzh>

4 files changed, 488 insertions, 0 deletions

diff --git a/api/gps-service-geolocation-with-states.yml b/api/gps-service-geolocation-with-states.yml
new file mode 100644
index 0000000..cd6a03e
--- /dev/null
+++ b/api/gps-service-geolocation-with-states.yml
@@ -0,0 +1,155 @@
+afbidl: "0.1"
+
+info:
+  title: Service for geolocation
+  description:
+        GPS service reports current WGS84 coordinates from GNSS devices
+        via the gpsd application.
+  version: "0.1"
+  author: AGL
+  maintainer: Scott Rifenbark
+  homepage: https://doc.automotivelinux.org/...
+
+generators:
+    genskel:
+        scope: static
+        prefix: req_
+        postfix: _cb
+        init: init_gps
+    #same model as book yaml
+    doc:
+        id: gps-api
+        keywords: gps
+        author:
+        version:
+        src_prefix: api-gps
+        chapters:
+        - name: Abstract
+          url: abstract.md
+        - name: User Guide
+          url: userguide.md
+
+api:
+    name: gps
+
+    verbs:
+
+        subscribe:
+            description: subscribe to gps/gnss events
+            request: $/schemas/subscription-desc
+            reply:
+                success:
+                    schema: $/schemas/none
+                    set-state:
+                        listening: yes
+
+        unsubscribe:
+            description: unsubscribe to gps/gnss events
+            request: $/schemas/subscription-desc
+            reply:
+                success:
+                    schema: $/schemas/none
+                    set-state:
+                        listening: no
+
+        location:
+            description: get current gps/gnss coordinates
+            request: $/schemas/none
+            reply:
+                success: $/schemas/location
+                _: An error can be returned when the service isn't ready
+
+        record:
+            description: |
+                Entering *record* mode you must send **{"state": "on"}** with the **record**
+                verb which will have a JSON response of **{"filename": "gps_YYYYMMDD_hhmm.log"}**
+                pointing to log under *app-data/agl-service-gps*
+
+                Now to enter *replaying* mode you must symlink or copy a GPS dump to
+                *app-data/agl-service-gps/recording.log* and restart the service.
+                From then on out the previously recorded GPS data will loop infinitely
+                which is useful for testing or demonstration purposes.
+            request: $/schemas/record/request
+            reply:
+                success:
+                    schema: $/schemas/record/reply
+                    set-state:
+                        recording: yes
+                _: An error can be returned when the service isn't ready
+
+    events:
+        location:
+            schema: $/schemas/location
+            when-state:
+                listening: yes
+
+    state-machines:
+        listening:
+            states: [ no, yes ]
+            initial: no
+        recording:
+            states: [ no, yes ]
+            initial: no
+
+# Follow JsonSchema specification (https://json-schema.org/)
+schemas:
+    subscription-desc:
+        title: Description of the event subscribed or unsubscribed
+        type: object
+        properties:
+            value: { enum: [ location ] }
+        required: [ value ]
+
+    location:
+        title: the location
+        type: object
+        properties:
+            altitude:
+                title: the altitude in meters above the normal geoide
+                type: number
+                minimum: -20000
+                maximum: 20000
+            latitude:
+                title: the latitude in degrees
+                type: number
+                minimum: -90
+                maximum: 90
+            longitude:
+                title: the longitude in degrees
+                type: number
+                minimum: -180
+                maximum: 180
+            speed:
+                title: the speed in meter per seconds m/s
+                type: number
+                minimum: 0
+                maximum: 6000
+            track:
+                title: the heading in degrees
+                type: number
+                minimum: 0
+                maximum: 360
+            timestamp:
+                title: time stamp of the location as a ISO8601 date
+                type: string #ISO8601
+                pattern: \d{4,}-[01][0-9]-[0-3][0-9]T[012][0-9]:[0-5][0-9]:[0-5][0-9].*
+
+    record:
+        request:
+            type: object
+            properties:
+                state: { const: "on" }
+            required: [ state ]
+
+        reply:
+            type: object
+            properties:
+                filename:
+                    title: the name of the file that records the data of format gps_YYYYMMDD_hhmm.log
+                    type: string
+                    pattern: gps_\d{4}\d{2}\d{2}_\d{2}\d{2}.log
+            required: [ filename ]
+
+    none:
+        title: no value, just null
+        const: null
diff --git a/api/gps-service-geolocation.html b/api/gps-service-geolocation.html
new file mode 100644
index 0000000..1191c9f
--- /dev/null
+++ b/api/gps-service-geolocation.html
@@ -0,0 +1,113 @@
+<html>
+<body>
+<h1>Documentation of gps</h1>
+
+<h2>Service for geolocation</h2>
+
+GPS service reports current WGS84 coordinates from GNSS devices via the gpsd application.
+
+
+<table>
+<tr><td>Version:</td><td>0.1</td></tr>
+<tr><td>Author:</td><td>AGL</td></tr>
+<tr><td>Maintainer:</td><td>Scott Rifenbark</td></tr>
+<tr><td>Site:</td><td>https://doc.automotivelinux.org/...</td></tr>
+</table>
+
+
+<h2>Verbs</h2>
+
+<ul>
+ <li><a href="#verb-subscribe">subscribe</a></li>
+ <li><a href="#verb-unsubscribe">unsubscribe</a></li>
+ <li><a href="#verb-location">location</a></li>
+ <li><a href="#verb-record">record</a></li>
+
+</ul>
+
+
+<h2>Events</h2>
+<ul>
+ <li><a href="#event-location">location</a></li>
+
+</ul>
+
+
+
+<h2>Events</h2>
+<ul>
+ <li><a href="#SM-listening">listening</a></li>
+ <li><a href="#SM-recording">recording</a></li>
+
+</ul>
+
+
+
+<a id="verb-subscribe"></a><h2>Verb subscribe</h2>
+
+<p>subscribe to gps/gnss events</p>
+
+<p><b>request:</b> { "title": "Description of the event subscribed or unsubscribed", "type": "object", "properties": { "value": { "enum": [ "location" ] } }, "required": [ "value" ] }</p>
+
+
+<p><b>reply success:</b> { "schema": { "title": "no value, just null", "const": null }, "set-state": { "listening": true } }</p>
+
+
+
+<a id="verb-unsubscribe"></a><h2>Verb unsubscribe</h2>
+
+<p>unsubscribe to gps/gnss events</p>
+
+<p><b>request:</b> { "title": "Description of the event subscribed or unsubscribed", "type": "object", "properties": { "value": { "enum": [ "location" ] } }, "required": [ "value" ] }</p>
+
+
+<p><b>reply success:</b> { "schema": { "title": "no value, just null", "const": null }, "set-state": { "listening": false } }</p>
+
+
+
+<a id="verb-location"></a><h2>Verb location</h2>
+
+<p>get current gps/gnss coordinates</p>
+
+<p><b>request:</b> { "title": "no value, just null", "const": null }</p>
+
+
+<p><b>reply success:</b> { "title": "the location", "type": "object", "properties": { "altitude": { "title": "the altitude in meters above the normal geoide", "type": "number", "minimum": -20000, "maximum": 20000 }, "latitude": { "title": "the latitude in degrees", "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "title": "the longitude in degrees", "type": "number", "minimum": -180, "maximum": 180 }, "speed": { "title": "the speed in meter per seconds m\/s", "type": "number", "minimum": 0, "maximum": 6000 }, "track": { "title": "the heading in degrees", "type": "number", "minimum": 0, "maximum": 360 }, "timestamp": { "title": "time stamp of the location as a ISO8601 date", "type": "string", "pattern": "\\d{4,}-[01][0-9]-[0-3][0-9]T[012][0-9]:[0-5][0-9]:[0-5][0-9].*" } } }</p>
+
+<p><b>reply _:</b> An error can be returned when the service isn't ready</p>
+
+
+
+<a id="verb-record"></a><h2>Verb record</h2>
+
+<p>Entering *record* mode you must send **{"state": "on"}** with the **record**
+verb which will have a JSON response of **{"filename": "gps_YYYYMMDD_hhmm.log"}**
+pointing to log under *app-data/agl-service-gps*
+
+Now to enter *replaying* mode you must symlink or copy a GPS dump to
+*app-data/agl-service-gps/recording.log* and restart the service.
+From then on out the previously recorded GPS data will loop infinitely
+which is useful for testing or demonstration purposes.
+</p>
+
+<p><b>request:</b> { "type": "object", "properties": { "state": { "const": "on" } }, "required": [ "state" ] }</p>
+
+
+<p><b>reply success:</b> { "schema": { "type": "object", "properties": { "filename": { "title": "the name of the file that records the data of format gps_YYYYMMDD_hhmm.log", "type": "string", "pattern": "gps_\\d{4}\\d{2}\\d{2}_\\d{2}\\d{2}.log" } }, "required": [ "filename" ] }, "set-state": { "recording": true } }</p>
+
+<p><b>reply _:</b> An error can be returned when the service isn't ready</p>
+
+
+
+
+
+<a id="event-location"></a><h2>Event location</h2>
+
+
+
+<a id="SM-listening"></a><h2>State Machine listening</h2>
+
+<a id="SM-recording"></a><h2>State Machine recording</h2>
+
+
+
diff --git a/api/gps-service-geolocation.yml b/api/gps-service-geolocation.yml
new file mode 100644
index 0000000..805eab0
--- /dev/null
+++ b/api/gps-service-geolocation.yml
@@ -0,0 +1,135 @@
+afbidl: "0.1"
+
+info:
+  title: Service for geolocation
+  description:
+        GPS service reports current WGS84 coordinates from GNSS devices
+        via the gpsd application.
+  version: "0.1"
+  author: AGL
+  maintainer: Scott Rifenbark
+  homepage: https://doc.automotivelinux.org/...
+
+generators:
+    genskel:
+        scope: static
+        prefix: req_
+        postfix: _cb
+        init: init_gps
+    #same model as book yaml
+    doc:
+        id: gps-api
+        keywords: gps
+        author:
+        version:
+        src_prefix: api-gps
+        chapters:
+        - name: Abstract
+          url: abstract.md
+        - name: User Guide
+          url: userguide.md
+
+api:
+    name: gps
+
+    verbs:
+
+        subscribe:
+            description: subscribe to gps/gnss events
+            request: $/schemas/subscription-desc
+            reply:
+                success: $/schemas/none
+
+        unsubscribe:
+            description: unsubscribe to gps/gnss events
+            request: $/schemas/subscription-desc
+            reply:
+                success: $/schemas/none
+
+        location:
+            description: get current gps/gnss coordinates
+            request: $/schemas/none
+            reply:
+                success: $/schemas/location
+                _: An error can be returned when the service isn't ready
+
+        record:
+            description: |
+                Entering *record* mode you must send **{"state": "on"}** with the **record**
+                verb which will have a JSON response of **{"filename": "gps_YYYYMMDD_hhmm.log"}**
+                pointing to log under *app-data/agl-service-gps*
+
+                Now to enter *replaying* mode you must symlink or copy a GPS dump to
+                *app-data/agl-service-gps/recording.log* and restart the service.
+                From then on out the previously recorded GPS data will loop infinitely
+                which is useful for testing or demonstration purposes.
+            request: $/schemas/record/request
+            reply:
+                success: $/schemas/record/reply
+                _: An error can be returned when the service isn't ready
+
+    events:
+        location: $/schemas/location
+
+# Follow JsonSchema specification (https://json-schema.org/)
+schemas:
+    subscription-desc:
+        title: Description of the event subscribed or unsubscribed
+        type: object
+        properties:
+            value: { enum: [ location ] }
+        required: [ value ]
+
+    location:
+        title: the location
+        type: object
+        properties:
+            altitude:
+                title: the altitude in meters above the normal geoide
+                type: number
+                minimum: -20000
+                maximum: 20000
+            latitude:
+                title: the latitude in degrees
+                type: number
+                minimum: -90
+                maximum: 90
+            longitude:
+                title: the longitude in degrees
+                type: number
+                minimum: -180
+                maximum: 180
+            speed:
+                title: the speed in meter per seconds m/s
+                type: number
+                minimum: 0
+                maximum: 6000
+            track:
+                title: the heading in degrees
+                type: number
+                minimum: 0
+                maximum: 360
+            timestamp:
+                title: time stamp of the location as a ISO8601 date
+                type: string #ISO8601
+                pattern: \d{4,}-[01][0-9]-[0-3][0-9]T[012][0-9]:[0-5][0-9]:[0-5][0-9].*
+
+    record:
+        request:
+            type: object
+            properties:
+                state: { const: "on" }
+            required: [ state ]
+
+        reply:
+            type: object
+            properties:
+                filename:
+                    title: the name of the file that records the data of format gps_YYYYMMDD_hhmm.log
+                    type: string
+                    pattern: gps_\d{4}\d{2}\d{2}_\d{2}\d{2}.log
+            required: [ filename ]
+
+    none:
+        title: no value, just null
+        const: null
diff --git a/api/mkapihtml b/api/mkapihtml
new file mode 100755
index 0000000..c9da31d
--- /dev/null
+++ b/api/mkapihtml
@@ -0,0 +1,85 @@
+#/bin/sh
+set -e
+
+f="$1"
+test -f "$f"
+
+t="$(mktemp)"
+
+y2j() {
+ python -c 'import sys, yaml, json; y=yaml.load(sys.stdin.read()); print(json.dumps(y))'
+}
+
+sed 's%[$]\(/[^ \t]*\)%{ $ref: "#\1" }%' "$f" | \
+ y2j | \
+ afb-exprefs |
+ jq . > "$t"
+
+h="$(mktemp)"
+cat << EOC > "$h"
+<html>
+<body>
+<h1>Documentation of {{api.name}}</h1>
+
+<h2>{{info.title}}</h2>
+
+{{info.description}}
+
+{{#info}}
+<table>
+<tr><td>Version:</td><td>{{version}}</td></tr>
+<tr><td>Author:</td><td>{{author}}</td></tr>
+<tr><td>Maintainer:</td><td>{{maintainer}}</td></tr>
+<tr><td>Site:</td><td>{{homepage}}</td></tr>
+</table>
+{{/info}}
+
+<h2>Verbs</h2>
+
+<ul>
+{{#api.verbs.*}} <li><a href="#verb-{{*}}">{{*}}</a></li>
+{{/api.verbs.*}}
+</ul>
+
+{{#api.events}}
+<h2>Events</h2>
+<ul>
+{{#*}} <li><a href="#event-{{*}}">{{*}}</a></li>
+{{/*}}
+</ul>
+{{/api.events}}
+
+{{#api.state-machines}}
+<h2>Events</h2>
+<ul>
+{{#*}} <li><a href="#SM-{{*}}">{{*}}</a></li>
+{{/*}}
+</ul>
+{{/api.state-machines}}
+
+{{#api.verbs.*}}
+<a id="verb-{{*}}"></a><h2>Verb {{*}}</h2>
+
+<p>{{description}}</p>
+
+<p><b>request:</b> {{request}}</p>
+
+{{#reply.*}}
+<p><b>reply {{*}}:</b> {{.}}</p>
+{{/reply.*}}
+
+{{/api.verbs.*}}
+
+{{#api.events.*}}
+<a id="event-{{*}}"></a><h2>Event {{*}}</h2>
+{{/api.events.*}}
+
+{{#api.state-machines.*}}
+<a id="SM-{{*}}"></a><h2>State Machine {{*}}</h2>
+{{/api.state-machines.*}}
+
+
+EOC
+
+mustach "$t" "$h"
+rm "$t" "$h"