Providing an OpenAPI specification

[dersvenhesse]

Hello,
first of all, thank you for directly adding models based on the json-schema in https://github.com/MobilityData/gbfs-json-schema. This helps a lot. Hereby I'd like to suggest another addition to the toolbox: a generic OpenAPI specification for GBFS.

In my knowledge developers often use OpenAPI specification (https://spec.openapis.org/oas/latest.html) to describe their (restful) apis. The brings possibilities to document the usage, add examples, provide additional descriptions, having support for multiple programming languages (similar to json-schema) all while providing consumers an easy-to-use and built-in tryout.

With a pre-existing specification providers only need to update some fields (like servers and info) and have a widely recognized documentation ready. Providers as well as consumers can easily use generators (like https://openapi-generator.tech/) to create code for implementation and usage.

I'd suggest one specification with all feeds combined, but I'm happy to discuss other alternatives.
I'd also be happy to provide the first draft if you folks also think this might be a good addition.

[richfab]

Hi @dersvenhesse!

Extending your thanks to @testower, @tdelmas and @Alessandro100 for adding models based on the json-schema 🙏

Thank you for this great suggestion about having a generic OpenAPI specification for GBFS. Would you mind sharing examples of such API for other data standards?

If other members of the community find this useful, please add a 👍 on the issue description like @futuretap.

Thanks!

[mplsmitch]

Would you mind sharing examples of such API for other data standards?

There are OpenAPI descriptions for MDS and CDS.

MDS here:
https://github.com/openmobilityfoundation/mds-openapi
https://openmobilityfnd.stoplight.io/docs/mds-openapi/gqf2ey431nxzh-about-mds

CDS here:
https://github.com/openmobilityfoundation/cds-openapi
https://openmobilityfnd.stoplight.io/docs/cds-openapi/83teyinnn1py6-curb-api

[richfab]

Thank you @mplsmitch for these beautiful examples, it's very useful 🤩

@dersvenhesse We'd be very happy to welcome your first draft for an OpenAPI specification for GBFS.

I'm moving this issue to the repo where the code will likely be hosted. Please use this repo for your draft: https://github.com/MobilityData/gbfs-json-schema

Thank you! 🙏

[davidgamez]

Closed by #138 for the 2.3 version.

[davidgamez]

Latest v3.1-RC version will be addressed in #143