We don't set util.Time to date-time... intentional?

Swagger 1.2 and 2.0 don't support TRACE - OAI/OpenAPI-Specification#325

This would be awesome.

cc @RichieEscarez @nikhiljindal

date-time: Not intentional: #2968

Other known issues:

• Some struct fields missing in swagger-spec #6842
• Document API return values in swagger #6167
• Swagger represents all maps as type "any" #4700
• Document custom JSON types in swagger #2971
• Embed doc URLs in swagger documentation #3059
• Duplicate replacePod APIs defined in spec #7100
• Attach documentation to API types and/or resources #5331
• Add validation constraints to API struct tags #8116

Will have an example of the output shortly so you can see what it looks like.

Yes this would be great (@MikeJeffrey and I recently discussed the need for this)!

Examples http://docs.openshift.org/latest/rest_api/openshift_v1.html and http://docs.openshift.org/latest/rest_api/kubernetes_v1.html

swagger2markup can also inline descriptions - that was used to get http://docs.openshift.org/latest/rest_api/kubernetes_v1.html#v1-persistentvolumeclaim

Cool. Inlined from where?

Directory structure - the generator looks for a file in a directory that corresponds to the name of the object or the name of the topic. It slurps in the asciidoc file and then generates the rest of the structure.

On Jun 3, 2015, at 1:15 AM, Brian Grant notifications@github.com wrote:

Cool. Inlined from where?

—
Reply to this email directly or view it on GitHub.

@smarterclayton does Markdown get automatically generated too (along with the AsciiDoc you use)? Im working on moving our user doc into GitHub pages and would like a copy of the API in Markdown.

swagger2markup can output to Markdown. Asciidoc is the default.

----- Original Message -----

@smarterclayton does Markdown get automatically generated too (along with the
AsciiDoc you use)? Im working on moving our user doc into GitHub pages and
would like a copy of the API in Markdown.

---

Reply to this email directly or view it on GitHub:
#9097 (comment)

Any progress on this?

Will open a pull next week when I get back from PTO

@andronat pointed out Slate on #11253

We're doing this now.

@caesarxuchao @nikhiljindal @RichieEscarez Anything we should fork off this issue before closing?

I don't have more issues.

I think the inconsistency between the GitHub repo and the Kubernetes.io versions of the API should be resolved.

Issue:
Today, out on Kubernetes.io, we override all the embedded CSS that is included with the current versions of these html formatted API files in order for it to display with the same color and font as our other docs.

From in the Github repo, the raw versions of these API files get inconsistently displayed in a different color.

Aside from the color and font differences between our two sources, the header in both files is also different (path vs. operations).

Possible solutions:

• output to markdown instead (convert it to HTML for the kubernetes site like all other docs)
• output html files with Kubernetes specific CSS (same color and font as our site)

I think the inconsistency between the GitHub repo and the Kubernetes.io versions of the API should be resolved.

I don't know if this is necessary, they are two different websites, people won't expect the format to be the same.

Aside from the color and font differences between our two sources, the header in both files is also different (path vs. operations).

Good catch, this could be fixed by adding a line in https://github.com/kubernetes/kubernetes/blob/master/hack/gen-swagger-doc/gen-swagger-docs.sh and update the container image. Sorry I don't have time to do that this week.

[update]
this is fixed.

@nikhiljindal We should fork another issue to track all of the swagger problems.

Re:
... the header in both files is also different (path vs. operations).

@caesarxuchao fixed the page title mismatch in #15040

There is also: #15343

What's left to do here?

There are no big problems, but several enhancements nice to have. The left issues from smarterclayton's first comment

• Swagger model order is random because ApiDeclarations.Models is a map[string]Object. We need to convert it to a []... in the swagger serialization format.
• Our operation descriptions should be capitalized - those are used as headers and TOC lines in doc
• Our paths should have descriptions like "Use this path to operate on lists of Pods", "Use this path to operate on individual Pods", "Use this path to control the status of a Pod"
• PATCH documents don't properly document their body parameter model type (no schema) - should be "any" which we can probably make happen with map[string]interface{}. (see if http://kubernetes.io/v1.1/docs/api-reference/v1/definitions.html#_unversioned_patch is good enough?)

This was done by many people.