Add API reference docs from swagger

[discordianfish]

I think it would be super useful to have API docs on the site. Like https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/ they should get generated from the swagger definition.

[discordianfish]

This is how it's done for Kubernetes: https://github.com/kubernetes/kubernetes/blob/8993fbc543c18e73668793b5d5e234c0a136735c/hack/gen-swagger-doc/gen-swagger-docs.sh

[rbreeze]

@discordianfish As I was looking at the REST docs earlier today I was thinking the same thing. Having them available without having to copy / paste into the Swagger editor would make it that much easier for people to access the docs and use the API. I'll try that script when I have a bit of free time.

[rbreeze]

It seems that script anticipates some of the documentation to be in AsciiDoc so I'm not sure it can be modified to work in this case. However, Swagger Codegen can generate static HTML from a Swagger doc (through several different methods) as per this StackOverflow post. I think the issue once the actual HTML generation itself is figured out is how to automate that generation upon swagger file changes.

[discordianfish]

@jessesuen What do you think? ^