Where is the OpenAPI?

[philsturgeon]

Hello! Thanks for making this API.

On your homepage you talk about "OpenAPI" when I think you mean "an open API", which is a little confusing because it seems like you do also use "OpenAPI" somewhere, but hide the source YAML and publish a HTML rendering of it? Minefield! :D

Two things that would help any further confusion here:

1. Could you change the marketing copy to say "open API" so people know you just mean a public API?

2. Could you have a look at some of the modern OpenAPI-based doc tools like Stoplight Elements or ReDoc? They're open source and will convert your YAML > Widdershins > MD > HTML pipeline into "YAML is read and turned into HTML" which doesn't even need a build step.

LMK if you want any help with any of it.

[mijiturka]

Adding the source yaml to the repo would also help people contribute pull requests, e.g fixing issues in current code samples, or adding new languages for them.

Edit: nvm, I think they already know 0a3576d

[philsturgeon]

If OpenAPI and API code are getting out of sync there's loads of ways to fix that.

It's called the API Desgin First (and Evolve) workflow: https://apisyouwonthate.com/blog/api-design-first-vs-code-first