api-definitions icon indicating copy to clipboard operation
api-definitions copied to clipboard

Published 20 hours ago • verified publisher icon carbon-intensity

Where is the OpenAPI?

Open philsturgeon opened this issue 2 years ago • 2 comments

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.

philsturgeon avatar Dec 02 '22 19:12 philsturgeon