Generating documentation for client libraries

[buremba]

Even though their functions are same, each client api has different usages since each programming language has its own syntax and conventions.

Statically-typed languages such as Java has automatic api generators (javadoc) but in dynamically-typed languages users will have to look at the source code in order to use client libraries since there won't be any example of how the client library can be used.

It would be nice to generate documentations for client libraries that are also generated by swagger-codegen. The generated documentation will actually be similar to API documentation, except it will demonstrate constructing objects, passing parameters and executing queries.

[wing328]

@buremba thanks for the feedback. Here is a similar suggestion opened before: #1363

[ghost]

I'm working on generating Slate documentation. Will PR once I am done. Not sure how long it will be though!

[buremba]

@jhitchcock I started a separate project that generates Slate markdown from Swagger specification. It's still far from being mature but may be helpful for you. https://github.com/buremba/swagger-slate

Currently, it uses custom template files and have swagger-codegen dependency in order to generate example usage section of Slate for different languages.

[wing328]

UPDATE: html2 generates documentation with code samples.