Swagger-codegen: Add auto-generated documentation

[wing328]

We've add capabilities to generate documentation files (markdown) for API and model files in the Perl code generator: #2320, #2343

If anyone has cycle to add the documentation to the following languages, please reply to let us know:

• [x] Android (#2773)
• [ ] Bash
• [ ] C++
• [x] C# (https://github.com/swagger-api/swagger-codegen/pull/2595)
• [ ] Clojure
• [x] Dart (https://github.com/swagger-api/swagger-codegen/pull/4291)
• [ ] Elixir
• [ ] Flash
• [x] Go (https://github.com/swagger-api/swagger-codegen/pull/2608)
• [ ] Groovy
• [x] Javascript (https://github.com/swagger-api/swagger-codegen/pull/2391)
• [x] Java (https://github.com/swagger-api/swagger-codegen/pull/2435)
• [x] ObjC (https://github.com/swagger-api/swagger-codegen/pull/2482)
• [x] Perl (#2320, #2343)
• [x] PHP (https://github.com/swagger-api/swagger-codegen/pull/2388)
• [x] Python (https://github.com/swagger-api/swagger-codegen/pull/2472)
• [x] Ruby (#2344)
• [ ] Swift
• [ ] Scala
• [ ] TypeScript

[wing328]

Here is an example for Perl Petstore: https://github.com/wing328/swagger-petstore-perl#documentation-for-api-endpoints

[KevinGlinski]

I can pick up the c# doc, doesn't look like anyone is working on it.

[wing328]

@KevinGlinski Thanks Kevin. Saw your PR (https://github.com/swagger-api/swagger-codegen/pull/2595)

[Vrolijkx]

I will look into the typescript doc

[jfiala]

There is already a nice Swagger2Markup converter (Java-based) called Swagger2Markup (https://github.com/Swagger2Markup/swagger2markup), which supports conversion of the Swagger definition to asciidoctor files and then to HTML and PDF, everything available as maven-tasks, if this helps...

[wing328]

@jfiala yes, I'm aware of Swagger2Markup and it looks good.

From what I know, Swagger2Markup does not contain installation instruction nor code sample/getting start section to more easily onboard the developers.

[jfiala]

@wing328: it provides a maven integration template which shows all steps necessary (Swagger -> Asciidoctor -> HTML/PDF):
https://github.com/Swagger2Markup/swagger2markup-maven-project-template/

So it should be no problem to pick it up and use it....

[wing328]

For installation instruction and code sample/getting start section, I was referring to the auto-generated SDKs, not Swagger2Markup itself.

In other words, this task aims to provide documentation for the auto-generated SDK in a particular language.

Here is a an example: https://github.com/wing328/test-python

[jfiala]

ok, sorry - I wasn't sure if an additional documentation for the client is needed if there's already the API documentation...

[ramzimaalej]

@wing328 I raised a PR for Akka-Scala

https://github.com/swagger-api/swagger-codegen/pull/7027

[atbe]

Is there any way we can disable the generating of documentation? In my case it's necessary and is causing heap errors because there is not enough memory on the machine. All I want to generate is the code.

[wing328]

@atbe One way is to use .swagger-codegen-ignore to whitelist the documentation folder.

[atbe]

@wing328 Yep, that's exactly how I ended up doing it. Thanks!