Add support for Swagger/Open Api Spec

[omerlh]

Expected Behavior

I want to have a client for OPA for my language (e.g. C3)

Actual Behavior

Need to write it manually.

Additional Info

Please add support for either Swagger or API spec that allows generating clients for any language.

[tsandall]

@omerlh it would be nice to have an Open API spec for OPA. One thing I'd be concerned about is drift between the REST API documentation and the Open API spec. Having tooling to generate one from the other would be a requirement.

The current REST API documentation can be found under docs/content/rest-api.md. It would be acceptable to move the source of truth into an Open API JSON document and would get used to generate the REST API page.

/cc @patrick-east @lucperkins

[lucperkins]

@tsandall Agreed that this is the preferred approach. If your people can create a YAML or JSON spec (preferably YAML, largely due to commentability), I can write the necessary CSS and static site generator bits to display it on the REST API page.

[patrick-east]

+1 for having an openapi spec and generating the API docs from it (means we have to keep the spec updated and well documented.. so thats good news 😄 )

One cool thing that could come from having this is (potentially) testing around the generated client code so we can validate that the spec+docs+server are all in sync.

[gazconroy]

Hi

I'm a technical writer with a good few years under my belt and picking up open source API documentation projects for my portfolio.

The existing markdown files for the project provide a great basis for generating an Open API specification. Let me know if you're interested in my lending a hand.

[anderseknert]

Sounds interesting @gazconroy! Perhaps we could sync on this on the bi-weekly community meeting tomorrow? See the README for details.

[stale]

This issue has been automatically marked as inactive because it has not had any activity in the last 30 days.

[stale]

This issue has been automatically marked as inactive because it has not had any activity in the last 30 days.

[anderseknert]

Oh, I had apparently missed to close this. Open API specs for OPA may be found in the contrib repo. Thanks @gazconroy for your work on this!