openAPI.yaml generators

[feep]

@ramfox wanted a list of tools that can generate openapi.yaml api files from annotated source.

In addition to generating .yaml the go tools can generate documentation that could be served from qri connect.

The go-specific tools also can use struct annotation so you don’t have to chase every code change with a comment change.

• swag

  • go specific
  • 3k+ stars
  • doesn’t support openAPI 3 yet (1, 2)
  • struct annotation

• apidoc

  • looks like it was written (forked?) specifically because swag did not support openAPI 3
  • go specific
  • 8 stars
  • openAPI 3
  • may not generate docs to be served with net/http
  • struct annotation

• swagger-inline

  • generic
  • node.js
  • 80 stars
  • maintained by a (currently) funded company

There are probably more. But that’s all I’m going to look for for now. Let me know if you want more.

[feep]

@ramfox, I am happy to take this issue and move the .yaml docs into api.go for you.

...if that’s the direction you want to go.

...and if now is the time to go that direction.

[ramfox]

@b5 would love your weigh in, but I think that we do want our docs to be automated and I think now _is_the time to do it. Having incorrect docs up feels just as bad as having no docs.

I understand that having python docs up asap is a concern as well, tho, so if this isn't the exact moment, then right after python docs would be my vote.

[feep]

And, as a note, we don’t care about the ability to serve static(?) api docs from go (in qri connect, for example).

The doc viewer we’re using (and others) can display api docs from just the .yaml.