New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improved API documentation #555

Closed
blalor opened this Issue Dec 23, 2014 · 15 comments

Comments

Projects
None yet
@blalor
Contributor

blalor commented Dec 23, 2014

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

This comment has been minimized.

Show comment
Hide comment
@blalor

blalor Dec 23, 2014

Contributor

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. :-)

Contributor

blalor commented Dec 23, 2014

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

This comment has been minimized.

Show comment
Hide comment
@blalor

blalor Dec 28, 2014

Contributor

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.

Contributor

blalor commented Dec 28, 2014

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

This comment has been minimized.

Show comment
Hide comment
@blalor

blalor Dec 30, 2014

Contributor

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.

Contributor

blalor commented Dec 30, 2014

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

This comment has been minimized.

Show comment
Hide comment
@davidpelfree

davidpelfree Dec 30, 2014

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.

davidpelfree commented Dec 30, 2014

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

This comment has been minimized.

Show comment
Hide comment
@blalor

blalor Dec 30, 2014

Contributor

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.=

Contributor

blalor commented Dec 30, 2014

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

This comment has been minimized.

Show comment
Hide comment
@armon

armon Jan 2, 2015

Member

@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?

Member

armon commented Jan 2, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@blalor

blalor Jan 2, 2015

Contributor

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.

Contributor

blalor commented Jan 2, 2015

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

This comment has been minimized.

Show comment
Hide comment
@sethvargo

sethvargo Jan 2, 2015

Contributor

@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.

Contributor

sethvargo commented Jan 2, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@rotatingJazz

rotatingJazz Jan 11, 2015

@blalor Awesome 👍 🍻

rotatingJazz commented Jan 11, 2015

@blalor Awesome 👍 🍻

@dellis23

This comment has been minimized.

Show comment
Hide comment
@dellis23

dellis23 Feb 15, 2015

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.

dellis23 commented Feb 15, 2015

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.

@blalor blalor referenced this issue Oct 16, 2015

Closed

Dash docset #1314

@mtyrrell

This comment has been minimized.

Show comment
Hide comment
@mtyrrell

mtyrrell Aug 19, 2016

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

mtyrrell commented Aug 19, 2016

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

This comment has been minimized.

Show comment
Hide comment
@bluefeet

bluefeet Sep 14, 2016

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.

bluefeet commented Sep 14, 2016

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

This comment has been minimized.

Show comment
Hide comment
@slackpad

slackpad May 1, 2017

Contributor

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

Contributor

slackpad commented May 1, 2017

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

@slackpad slackpad closed this May 1, 2017

@kinlane

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane Jan 8, 2018

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.

kinlane commented Jan 8, 2018

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

This comment has been minimized.

Show comment
Hide comment
@tfhartmann

tfhartmann Feb 28, 2018

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?

tfhartmann commented Feb 28, 2018

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment