search

MobilityData / gbfs-json-schema

JSON Schema for GBFS feeds, managed by MobilityData. The versions are organized by folders. CC BY 4.0
Apache License 2.0
23 stars 24 forks source link

Providing an OpenAPI specification #136

Open dersvenhesse opened 1 month ago

dersvenhesse commented 1 month ago

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 commented 2 weeks ago

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 commented 2 weeks ago

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 commented 2 weeks ago

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! 🙏