Kops API/Swagger Spec

[krisnova]

So now that we have a lovely kops API - I think we should get in the habit of documenting it. I think we should follow the kubernetes approach and generate a swagger spec/contract.

It would be great to look at generating a spec/contract from our go code as well! (I know, generating code that generates documentation.. right?) But having the notes from the API definition in go would be very valuable here!

My thought was to have a make target to support this

make docs

We could begin fleshing the target out with swagger functionality and autogen functionality for our documentation in general..

Wins:

1. Precursor for a kops website/.io
2. High level view into kops from a library/api perspective
3. Once we begin work on the HTTP layer, having this will almost be a must
4. Encouragement to write better code
5. Everybody loves API docs

[chrislovecnm]

So API docs make sense. With the swagger we need to figure out how we are making an API outa this :) If we embed this into the K8s API server, it may gen the swagger for us. Not sure.

[chrislovecnm]

We have PR inbound thay may help with this ... I am looking through issues to test against #1183

This can get us a swagger ... Any thing else?

[chrislovecnm]

Removing from #1206

[chrislovecnm]

We have this with the API server, can we close now?

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

Prevent issues from auto-closing with an /lifecycle frozen comment.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or @fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten
/remove-lifecycle stale

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

[punit-naik]

Can anyone post the link for swagger spec json here?