search

swagger-api / swagger-codegen

swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.
http://swagger.io
Apache License 2.0
16.88k stars 6.03k forks source link

Add auto-generated documentation #2359

Open wing328 opened 8 years ago

wing328 commented 8 years ago

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:

wing328 commented 8 years ago

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

KevinGlinski commented 8 years ago

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

wing328 commented 8 years ago

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

Vrolijkx commented 8 years ago

I will look into the typescript doc

jfiala commented 8 years ago

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 commented 8 years ago

@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 commented 8 years ago

@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 commented 8 years ago

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 commented 8 years ago

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

ramzimaalej commented 6 years ago

@wing328 I raised a PR for Akka-Scala

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

atbe commented 6 years ago

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 commented 6 years ago

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

atbe commented 6 years ago

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