search

openmobilityfoundation / cds-openapi

OpenAPI schema for CDS data feeds, managed by the Open Mobility Foundation. The versions are organized by folders.
Other
4 stars 0 forks source link

OpenAPI file structure for Stoplight documentation #5

Open michael-danko-passport opened 2 years ago

michael-danko-passport commented 2 years ago

Is your feature request related to a problem? Please describe.

When we are building out the OpenAPI files within Stoplight, I believe we need to align on how we should structure the YAML files.

Describe the solution you'd like

I would like to pursue Option B which is the creation of a YAML file for each of the CDS APIs (Events, Curb, Metrics). This could make the documentation modular and easier to digest when being displayed through Stoplight.

Is this a breaking change

This isn't a breaking change since we have yet to finalize a full Open API version on our documentation

Impacted Spec

All APIs are impacted with this documentation standard.

Describe alternatives you've considered

We would want to use Stoplight to create shared models that can be referenced by multiple APIs if these are needed. This proposed structure does not conflict with previous decisions to maintain a single branch for each API version.

Additional context

Several members of the CDS WGSC collectively showed support for the option to move towards a model where 3 distinct files were used to document each API in the Oct 11th WGSC meeting.

michael-danko-passport commented 2 years ago

@schnuerle We talked about this in today's WGSC meeting and would like to move forward with Option B but would like to get your thoughts since you were unable to join today's call.

michael-danko-passport commented 2 years ago

Update: I believe we have found the benefits of Option B without the rework of splitting the existing setup

While tweaking some things in Stoplilght, I made a change that tagged different endpoints. These changes were applied in this commit and the outcome allows us to group the endpoints by different APIs.

Example Screenshot: image

This will allow us to use the existing file that is in place which has several models created and are reused in the documentation.

schnuerle commented 1 year ago

We should structure this the same way we did for MDS. You can see that in action here: https://openmobilityfnd.stoplight.io/docs/mds-openapi

I'm going to move this issue to the OpenAPI repo.

michael-danko-passport commented 1 year ago

@schnuerle The changes I pushed out tonight should resolve this issue. We still need some WGSC eyes on this but the majority of the work has been completed to fix this issue.