Godoc for the API compatible with swagger generators

[calavera]

With this approach, we will be able to generate API documentation from go comments.
I think I like it better because it's less intrusive than moving to a
new router framework.

/cc @icecrime

Signed-off-by: David Calavera david.calavera@gmail.com

[duglin]

Is it worth doing this before the API split is done? I'd prefer to reduce the number of moving parts while we're trying to split things up.

/cc @kostickm

[calavera]

@duglin the thing is that we don't need to change router libraries if we use a static generator like this. I'm open to suggestions, I wanted to open both PRs so we can compare and decide.

I think this change is less intrusive.

[lyndaoleary]

I really like how Stripe/Paypal present their API docs: https://stripe.com/docs/api

https://github.com/tripit/slate provides a responsive template similar to Stripe's docs. It uses markdown for its documentation format.

I wonder if this might be useful for the Docker API docs. I put together a Docker theme. I added some of the existing content (markdown) to the template to see how it might look: http://lyndaoleary.github.io/docker-api-docs/#api-reference

It would be really cool if we could create something that would automatically generate markdown documentation based upon the Swagger spec 😄

[calavera]

@lyndaoleary I agree with you. The script in this PR already generates markdown, but I haven't had time to hook slate to it. Ideally, we'll probably want to generate as much static html as possible, and we'll probably have to bring some of the docker branding to the final look and feel.

I have more doc comments to add here, but I found a few issues with the generator.

[calavera]

@lyndaoleary PS: that looks very cool.

[calavera]

I removed all the generation scripts for now, they are slightly buggy. I think there are advantages to have the documentation in the code even though we don't generate the final output yet.

Please, take a look.

[thaJeztah]

@calavera could you help me out a bit here "what" needs to be reviewed, as I'm not sure (forgive my n00bishness);

Are the annotations used in this PR and existing standard, or something you invented/created?

If they're not an existing standard;

• Could you add documentation / a description of the format
• Should we have tests, to check if endpoints are correctly annotated?
• Do the annotations "conflict" with GoDoc? I.e., can a function both be documented with GoDoc, and these annotations, and what will the result be?

FWIW, I like the use of annotations for these!

Looking at these examples;

• Does @Description support longer descriptions/multiple lines? A single line may not be enough to describe an endpoint
• How to annotate an endpoint that can potentially return a different response based on, e.g., a "content-type" header
• As the above; how to describe the "content-type" that will be returned by an endpoint
• I only see annotations for @Success, not for @Error
• An endpoint can return different @Error; each potential error / error code should be described
• Kan we re-use the new error-package that @duglin has been working on, so that it's not needed to describe each error for an endpoint, if it's already documented on the error-type itself?

[calavera]

Okay, finally some time to address all @thaJeztah's comments 🎉

Could you add documentation / a description of the format

Indeed, should we explain how to document this handlers, which should include the list of supported annotations. The main concept is from http://beego.me/docs/advantage/docs.md

Should we have tests, to check if endpoints are correctly annotated?

I think that should be part of what we end up using to generate the final documentation. It could be part of the build if we wanted to do that, but I don't think it should be part of this.

Do the annotations "conflict" with GoDoc? I.e., can a function both be documented with GoDoc, and these annotations, and what will the result be?

Both are compatible. You can see an example at the beginning of the server file. The first line is GoDoc, the rest is api documentation. I added that because otherwise golint complains because the format of the comment is not correct. As you can see, it doesn't complain now.

Does @description support longer descriptions/multiple lines? A single line may not be enough to describe an endpoint

That's up to what we use to generate the final doc. From my point of view, I'd expect it to support several lines.

How to annotate an endpoint that can potentially return a different response based on, e.g., a "content-type" header.
As the above; how to describe the "content-type" that will be returned by an endpoint

This is up to consideration. I don't really have a good answer, I guess we could extend the @Success tag to support response headers. The parsers I've seen already allow you to have several @Success tags, btw.

I only see annotations for @success, not for @error
An endpoint can return different @error; each potential error / error code should be described

Agreed. @Error is a supported tag, and it behaves like @Success. I didn't include any because right not it quite hard to know all the possible errors a handler can return. I Expect this to be easier the more complete our errors package is.

Kan we re-use the new error-package that @duglin has been working on, so that it's not needed to describe each error for an endpoint, if it's already documented on the error-type itself?

Yes, this could be as easy as doing something like @Error 404 errors.ContainerNotFound. All the information about the error is already in the type.

I hope this answers all you comments. At the end of the day, I think most concerning things will rely on whatever we use to generate the final doc. I think, even if we never arrive to generate a final doc, this is very useful as a general purpose documentation in the code.

[thaJeztah]

I hope this answers all you comments.

Yes, it does, thanks! And, I agree that these annotations can be very useful; they give more structure to the way these endpoints are documented; would be interesting to see if we can use this to generate the stripe-docs that @lyndaoleary showed (#16125 (comment)) as well.

I'd be interested in @stevvooe's opinion/thoughts here; I know https://github.com/docker/distribution also generates documentation for the specs (don't know who actually wrote the code to generate that tbh)

[calavera]

would be interesting to see if we can use this to generate the stripe-docs that @lyndaoleary showed (#16125 (comment)) as well.

We can use this to generate markdown files. Slate uses plain markdown to render those pretty docs.