feat: add openapi specification (to discuss !136)

[dersvenhesse]

Hello, as suggested in !136 I created a specification for v2.3 to discuss the idea with a suggestion.

For now, the file is generated manually and contains mostly (conditionally) required feeds. All feeds are combined in a single specification separated by tags. How do you feel about this?

[Alessandro100]

Thank you for taking the initiative to work on this!

Personally I think splitting up the spec into smaller files would be best, but depending on how the generator works, I wouldn’t be totally against having a large file with tags

The yaml file should be moved under the models folder. It seems to be missing as few files: system_hours, system_alerts, system_calendar, system_regions, system_pricing_plans, geofencing_zone

We should include a Readme file that explains that the files were manually generated (link to the generator) as well as some basic instructions on how to use it. Also add it to the main Readme!

Hyped to keep expanding the gbfs dev tools

[dersvenhesse]

Thanks for your response and sorry for my delayed activity. I applied your notes and finished the file for v2.3. Does that look good to you?

Unfortunately, most generators from JSON schema to OpenAPI don't deliver satisfying results. I will look into automation and more versions (presumably v3.0) in an upcoming PR.

[dersvenhesse]

Do you have any feedback, @richfab or @Alessandro100?

[Alessandro100]

I’m interested in the use case of the openapi.yml file(s). Would the main use case be to generate language bindings for other languages?

For language binding generation it would be advisable to generate directly off the official gbfs .json schemas found in the repo. Example for Typescript and Golang could be found in

• scripts/generate_go_models.sh

• scripts/generate_typescript_models.sh

I’m also curious on the scalability of creating openapi.yml files for future gbfs versions. For version 2.3 was there a lot of manual intervention?

[dersvenhesse]

The are various use cases. A major one is the large amount of generators, which not only generate models but also nearly ready to use servers and clients. Take a look: https://openapi-generator.tech/docs/generators.

I manually created the file by copying attributes and descriptions from the json-schema, which is not future-proof. If the existing generators from JSON schema to OpenAPI won't deliver satisfying results, a custom converter script should do the job.

[Alessandro100]

I understand the use case and utility. If the main utility would be to generate code, I would remove the ## Usage section in the readme as we don’t want to promote a generator and be accountable for it

We should break up the openapi.yml file so that each component has its own .yaml file which will link to the main one. This will set a good precedent going forward for future openapi version additions. We are on a good path!

[dersvenhesse]

Thanks for the feedback. I originally added the ## Usage based on your comment on how to use the generator. Should I just link to their README or HOWTO instead?

Personally, I'd argue in favor of one openapi file instead of multiple. It is much easier to use with one file and many openapi meta information (server, description,...) and gbfs meta information (last_updated, ttl,...) will be redundant when using multiple files. Here is an real world example from ridedott.com with also one file, in that case even with multiple visibilities and versions.