Add OpenAPI spec to docs

[PartTimeDataScientist]

I've prepared an OpenAPI file for Photon for the developer documentation of the MOBIDROM Routing Services. Might be helpful for users of other Photon instances as well.

Redocly rendering of included OpenAPI spec is here

[lonvia]

The spec is not completely up-to-date. Some of the new parameters like include are missing.

While I'm very open to adding this, it means that we'd have two places with the same documentation. So ideally this comes with a script which converts openapi.json -> api-v1.md.

[lonvia]

Are these final line breaks really necessary? Shouldn´t spacing rather be fixed in the output renderer?

[PartTimeDataScientist]

You're right, this could/should be treated by the output renderer. I had added these to improve the Swagger-UI-Rendering for our Docs - but not every renderer might even understand HTML-Code in there. I'll remove them.

[lonvia]

It's curious that the OpenAPI spec seems to be rather silent on the question what format to use when adding rich text to the description. I'd expect that it is a requirement for every documentation to provide more than simple text.

[lonvia]

please add here "(for testing and low use only)"

[PartTimeDataScientist]

The spec is not completely up-to-date. Some of the new parameters like include are missing.

While I'm very open to adding this, it means that we'd have two places with the same documentation. So ideally this comes with a script which converts openapi.json -> api-v1.md.

Oh, must have missed that. Understand your point - I thought the api-v1.md to be "more verbose" than an OpenAPI-spec. I'd like to avoid writing a one off-script for this conversion.

However, I think it could be possible to extend the OpenAPI spec a bit further (although I don't know if it is reasonable to squeeze all content from the current api-v1.md into the OpenAPI spec) and then generate a markdown document from it, using e.g.

https://jsontotable.org/openapi-to-markdown
https://www.npmjs.com/package/@scalar/openapi-to-markdown

What do you think? If that sounds reasonable I'll try to extend the OpenAPI file so that it's a reasonable source for a markdown documentation...

[lonvia]

I was definitely thinking about a script to regularly use every time the openapi spec changes, not a one-off solution.

I'll try to extend the OpenAPI file so that it's a reasonable source for a markdown documentation...

Yes, that sounds like a good plan.

I'm not entirely convinced by the npm package you cite, as it claims to focus on LLM-friendly markdown, where I'm looking for human-friendly markdown. But that's rather an implementation detail. This being JSON, it should be fairly straightforward to generate markdown from a template afterwards. https://github.com/vrerv/openapi-markdown looks interesting, as it allows to use custom templates. We could then add any text that doesn't fit with OpenAPI, e.g remarks in the beginning of the file, to the template. Lets think about all that later.

Two more thoughts came up when I skimmed the OpenAPI spec:

It looks like there is a way to share parameter descriptions. That would be helpful. Any duplication that can be avoided makes maintenance easier. If you look into the query package, you can see where the source code shares parameter handling.

The other question would be if there is a particular reason you choose json over yaml. I don't have very strong opinions on that and would leave the final choice to whoever does the work. Personally though I find yaml slightly less tedious to edit.