Consul: Improved API documentation

[blalor]

I'd like to see better documentation for the HTTP API. By and large, the content that's published today is excellent, but I'd like to see it more normalized and consistent: at-a-glance info for supported verbs, response codes, parameters, etc. I don't know the current state of tools for documenting Go APIs, but something like Apiary or Swagger would be really useful for generating the docs programmatically. Akamai currently uses Apiary for their APIs, which is exactly what I'm after for Consul: https://developer.akamai.com/api/luna/papi/reference.html

[blalor]

I've set up a demo with Apiary. The source is here and the rendered documentation is at http://docs.consul.apiary.io/. I've only documented the KV endpoint, and only _very_ roughly. It took me longer than I'd hoped, but the KV endpoint is complex. :-)

[blalor]

Been thinking more about this and I really like what Apiary is doing. The mock client and hosted, rendered documentation are part of their platform, but the API Blueprint spec is open and there are other third-party tools like aglio that do an excellent job rendering static HTML.

[blalor]

Ok, I went a little overboard and ported all the docs to the API Blueprint format. ¯_(ツ)_/¯ The generated docs look really good and are, in my opinion, much more usable. Aglio has a few smallish problems, but I think it's a good starting point for static docs.

[davidpelfree]

Can also try Swagger which lets you also invoke methods on the fly!
And take the next step - embed swagger API definition inside Consul agent so URL can be invoked directly against this agent.

[blalor]

Swagger looks much more invasive to me; I like Apiary because it isn’t tightly coupled to the code. Apiary.io (the product) does provide a mock service, which can also act as a proxy to a real service.=

[armon]

@blalor Thanks for tackling this! The Apiary docs do look really good. I bet we can get pretty close to that by improving the docs generation we have now, instead of needing to link in an external service.

@sethvargo Thoughts? Any extensions to middleman we can use to make it more like Apiary and make the API doc experience nicer?

[blalor]

The real work was in creating the spec according to the API Blueprint schema. There's a pretty large tooling section that may have something appropriate for your doc generation system.

[sethvargo]

@armon I would like to move to standardized, versioned documentation for all our projects, but it's not something I have had time to research much.

[rotatingJazz]

@blalor Awesome :+1: :beers:

[dellis23]

To me, the biggest usability issues for the current docs for the HTTP API are:

1. A lack of linking to the sections in a sidebar that stays with the user.
2. A lack of scanability for the methods and parameters in general.

I frequently don't know _exactly_ what method I'm looking for, so I have to jump around a bit. If I were able to simple see from the beginning what sections contain the ability to let me list services, for instance, that would be satisfy 90% of my navigational needs.

[mtyrrell]

We would like to use a generated swagger.json schema as the basis for our Consul API clients. It seems like you could add support via : https://godoc.org/github.com/go-swagger/go-swagger

[bluefeet]

I'd also like to chime in to support Swagger. Swagger is just a way to specify how an API works, there is nothing that requires that it's tooling be somehow deeply integrated with an application. I've used it in projects to document my APIs, generate end-user documentation, generate "smoke" tests, generate basic skeletal client libraries in various languages, etc. The only part that was swagger was the specification document, the rest of it has been in-house tooling. Its just a specification.

[slackpad]

We just finished a revamp of the API docs and we don't have plans to support Swagger at this time.

[kinlane]

Sorry to post on a closed issue, but I took @blalor API Blueprint and generated an OpenAPI (fka Swagger) for Consul and published to Github - https://github.com/api-stack/hashicorp-consul-api. I am using this in a federal government project, and welcome any pull requests to improve upon. I'm using for documentation, client import using Postman, server code generation via Lambda, and for monitoring and testing. Ideally Consul would maintain their own, but seems like they only view OpenAPI (fka Swagger) as just about documentation, when it is so much more of an API consumer enablement tool.

[tfhartmann]

Hi there, I didn't want to open a new issue for this question, but I remember seeing this from @mitchellh https://twitter.com/mitchellh/status/952710186203951104 and was wondering where on the roadmap this might be?

[erikj180]

looks like it's been a year since the tweet and some clients are out of date. Would be awesome to see support of an openapi doc, v3 or v2. I have not seen any further discussion, when should we expect the feature on the roadmap?