feat: add openapi specification (to discuss !136) (#138)

* feat: add openapi draft (for v2.3)

* feat: finish openapi (for v2.3) and update documentation

* feat: simplify openapi.yaml with json-schema references; update readme

.gitignore

@@ -79,8 +79,8 @@ fabric.properties
 build/
 
 # Inputs and outputs
-/input/
-/output/
+input/
+output/
 
 # Mac
 */.DS_Store

README.md

@@ -1,12 +1,13 @@
 # gbfs-json-schema
-JSON Schema for [General Bikeshare Feed Specification(GBFS)](https://github.com/MobilityData/gbfs/blob/master/gbfs.md)  feeds, managed by MobilityData. The [gbfs-validator](https://github.com/MobilityData/gbfs-validator) links directly to them.
+JSON Schema for [General Bikeshare Feed Specification (GBFS)](https://github.com/MobilityData/gbfs/blob/master/gbfs.md) feeds, managed by MobilityData. The [gbfs-validator](https://github.com/MobilityData/gbfs-validator) links directly to them.
 
 ## Language Bindings
 
-* [TypeScript ](models/typescript/README.md)
-* [Java ](models/java/README.md)
-* [Golang ](models/golang/README.md)
-* [Rust ](models/rust/README.md)
+* [Golang](models/golang/README.md)
+* [Java](models/java/README.md)
+* [OpenAPI](models/openapi/README.md)
+* [TypeScript](models/typescript/README.md)
+* [Rust](models/rust/README.md)
 
 Are we missing your favorite language? Consider contributing:
 

models/openapi/README.md

@@ -0,0 +1,27 @@
+# GBFS OpenAPI Specification
+
+OpenAPI specifications for the General Bikeshare Feed Specification (GBFS) to easily create models and client code for existing GBFS systems or server code for your own implementation.
+
+## Usage
+
+### Code generation
+
+Many tools will let you generate models or client and server code direcly from the openapi file, e.g.
+
+* [OpenAPI Generator](https://openapi-generator.tech)
+* [Swagger Codegen](https://swagger.io/tools/swagger-codegen/)
+
+or one of [https://tools.openapis.org/categories/code-generators.html](these generators).
+
+### Customization
+
+The `openapi.yaml` can be extended with individual details within the `ìnfo` block. It's also recommended to add a `servers` block with your base root url, e.g.
+
+```
+servers:
+  - url: https://my.gbfs.org/v1
+```
+If needed, this can be overriden for a specific path.
+
+## Versions
+- v2.3

models/openapi/v2.3/openapi.yaml

@@ -0,0 +1,216 @@
+---
+openapi: 3.0.3
+info:
+    title: 'GBFS'
+    version: '2.3'
+    description: |-
+      OpenAPI specification for [General Bikeshare Feed Specification  (GBFS)](https://github.com/MobilityData/gbfs/blob/master/gbfs.md) feeds, managed by MobilityData.
+tags:
+    -   name: gbfs
+        externalDocs:
+            url: https://github.com/MobilityData/gbfs/blob/v2.3/gbfs.md#gbfsjson
+    -   name: gbfs_versions
+        externalDocs:
+            url: https://github.com/MobilityData/gbfs/blob/v2.3/gbfs.md#gbfs_versionsjson
+    -   name: system_information
+        externalDocs:
+            url: https://github.com/MobilityData/gbfs/blob/v2.3/gbfs.md#system_informationjson
+    -   name: vehicle_types
+        externalDocs:
+            url: https://github.com/MobilityData/gbfs/blob/v2.3/gbfs.md#vehicle_typesjson
+    -   name: station_information
+        externalDocs:
+            url: https://github.com/MobilityData/gbfs/blob/v2.3/gbfs.md#station_informationjson
+    -   name: station_status
+        externalDocs:
+            url: https://github.com/MobilityData/gbfs/blob/v2.3/gbfs.md#station_statusjson
+    -   name: free_bike_status
+        externalDocs:
+            url: https://github.com/MobilityData/gbfs/blob/v2.3/gbfs.md#free_bike_statusjson
+    -   name: system_hours
+        externalDocs:
+            url: https://github.com/MobilityData/gbfs/blob/v2.3/gbfs.md#system_hoursjson
+    -   name: system_calendar
+        externalDocs:
+            url: https://github.com/MobilityData/gbfs/blob/v2.3/gbfs.md#system_calendarjson
+    -   name: system_regions
+        externalDocs:
+            url: https://github.com/MobilityData/gbfs/blob/v2.3/gbfs.md#system_regionsjson
+    -   name: system_pricing_plans
+        externalDocs:
+            url: https://github.com/MobilityData/gbfs/blob/v2.3/gbfs.md#system_pricing_plansjson
+    -   name: system_alerts
+        externalDocs:
+            url: https://github.com/MobilityData/gbfs/blob/v2.3/gbfs.md#system_alertsjson
+    -   name: geofencing_zones
+        externalDocs:
+            url: https://github.com/MobilityData/gbfs/blob/v2.3/gbfs.md#geofencing_zonesjson
+paths:
+    /gbfs:
+        get:
+            tags:
+                - gbfs
+            operationId: getGbfs
+            responses:
+                '200':
+                    description: returns gbfs.json
+                    content:
+                        application/json:
+                            schema:
+                                $ref: https://raw.githubusercontent.com/MobilityData/gbfs-json-schema/refs/heads/master/v2.3/gbfs.json
+
+    /gbfs_versions:
+        get:
+            tags:
+                - gbfs_versions
+            operationId: getGbfsVersions
+            responses:
+                '200':
+                    description: returns gbfs_versions.json
+                    content:
+                        application/json:
+                            schema:
+                                $ref: https://raw.githubusercontent.com/MobilityData/gbfs-json-schema/refs/heads/master/v2.3/gbfs_versions.json
+
+    /system_information:
+        get:
+            tags:
+                - system_information
+            operationId: getSystemInformation
+            responses:
+                '200':
+                    description: returns system_information.json
+                    content:
+                        application/json:
+                            schema:
+                                $ref: https://raw.githubusercontent.com/MobilityData/gbfs-json-schema/refs/heads/master/v2.3/system_information.json
+
+    /vehicle_types:
+        get:
+            tags:
+                - vehicle_types
+            operationId: getVehicleTypes
+            responses:
+                '200':
+                    description: returns vehicle_types.json
+                    content:
+                        application/json:
+                            schema:
+                                $ref: https://raw.githubusercontent.com/MobilityData/gbfs-json-schema/refs/heads/master/v2.3/vehicle_types.json
+
+    /station_information:
+        get:
+            tags:
+                - station_information
+            operationId: getStationInformation
+            responses:
+                '200':
+                    description: returns station_information.json
+                    content:
+                        application/json:
+                            schema:
+                                $ref: https://raw.githubusercontent.com/MobilityData/gbfs-json-schema/refs/heads/master/v2.3/station_information.json
+
+    /station_status:
+        get:
+            tags:
+                - station_status
+            operationId: getStationStatus
+            responses:
+                '200':
+                    description: returns station_status.json
+                    content:
+                        application/json:
+                            schema:
+                                $ref: https://raw.githubusercontent.com/MobilityData/gbfs-json-schema/refs/heads/master/v2.3/station_status.json
+
+    /free_bike_status:
+        get:
+            tags:
+                - free_bike_status
+            operationId: getFreeBikeStatus
+            responses:
+                '200':
+                    description: returns free_bike_status.json
+                    content:
+                        application/json:
+                            schema:
+                                $ref: https://raw.githubusercontent.com/MobilityData/gbfs-json-schema/refs/heads/master/v2.3/free_bike_status.json
+
+    /system_hours:
+        get:
+            tags:
+                - system_hours
+            operationId: getSystemHours
+            responses:
+                '200':
+                    description: returns system_hours.json
+                    content:
+                        application/json:
+                            schema:
+                                $ref: https://raw.githubusercontent.com/MobilityData/gbfs-json-schema/refs/heads/master/v2.3/system_hours.json
+
+    /system_calendar:
+        get:
+            tags:
+                - system_calendar
+            operationId: getSystemCalendar
+            responses:
+                '200':
+                    description: returns system_calendar.json
+                    content:
+                        application/json:
+                            schema:
+                                $ref: https://raw.githubusercontent.com/MobilityData/gbfs-json-schema/refs/heads/master/v2.3/system_calendar.json
+
+    /system_regions:
+        get:
+            tags:
+                - system_regions
+            operationId: getSystemRegions
+            responses:
+                '200':
+                    description: returns system_regions.json
+                    content:
+                        application/json:
+                            schema:
+                                $ref: https://raw.githubusercontent.com/MobilityData/gbfs-json-schema/refs/heads/master/v2.3/system_regions.json
+
+    /system_pricing_plans:
+        get:
+            tags:
+                - system_pricing_plans
+            operationId: getSystemPricingPlans
+            responses:
+                '200':
+                    description: returns system_pricing_plans.json
+                    content:
+                        application/json:
+                            schema:
+                                $ref: https://raw.githubusercontent.com/MobilityData/gbfs-json-schema/refs/heads/master/v2.3/system_pricing_plans.json
+
+    /system_alerts:
+        get:
+            tags:
+                - system_alerts
+            operationId: getSystemAlerts
+            responses:
+                '200':
+                    description: returns system_alerts.json
+                    content:
+                        application/json:
+                            schema:
+                                $ref: https://raw.githubusercontent.com/MobilityData/gbfs-json-schema/refs/heads/master/v2.3/system_alerts.json
+
+    /geofencing_zones:
+        get:
+            tags:
+                - geofencing_zones
+            operationId: getGeofencingZones
+            responses:
+                '200':
+                    description: returns geofencing_zones.json
+                    content:
+                        application/json:
+                            schema:
+                                $ref: https://raw.githubusercontent.com/MobilityData/gbfs-json-schema/refs/heads/master/v2.3/geofencing_zones.json