Docfx: Feature request: Add swagger type definitions to REST API documentation

[Mangepange]

When generating a REST API documentation from a swagger-file I would expect that the types from the "definitions" section would be included in the documentation, especially if the type is used as a method parameter.

[vicancy]

https://github.com/dotnet/docfx/issues/465 describes the same feature. It is actually expanded in code however needs template support

[sirjeppe]

Hi! Any update on this issue?

[rebrovoleksii]

Could you please advise what template I should modify to get definitions into generated documentation? I've exported default.pdf template. Is it _exported_templates\pdf.default\partials\rest.child.tmpl.partial file? If yes what variables should I use from RestApi.common.js ?

[hellosnow]

@rebrovoleksii it should be _exported_templates\pdf.default\partials\rest.child.tmpl.partial we need to update for, the "definition" object is defined in child of RestApi.common.js. @vicancy to confirm.

[vicancy]

Hi @rebrovoleksii yes, it is the rest.child.tmpl.partial file. And to render complex type, for complex type, the type is actually inside the model however not rendered. You can use docfx build --exportViewModel to view the model waiting for applying template. Take body from updatePet for example, the detailed type for body is:

[ipanin]

Without support of Definitions swagger-generated documentation isn't usable. I'm waiting for its implementation. Also OpenAPI support required since it is more handy for REST API specification. For the present I am obliged to use ReDoc for the OpenAPI part of documentation.

[mattwoberts]

Hi - just wondered if this is planned at all? I too need the swagger generated docs to include the definitions, without this I'll have to find an alternative solution.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

[mcm-ham]

Thanks for the pointer vicancy, I've had a go at modifying the default template to add swagger type definitions support similar to what Microsoft already use.

https://mcm-ham.github.io/docfx-seed/restapi/petstore.html
https://github.com/mcm-ham/docfx-seed/commit/81151ef0a52da8cf07cf4b38061478d1b7c05ef1

[ipanin]

@mcm-ham, thanks a lot.
@vicancy, do you have any plans to embed this change to the default template?

[ipanin]

Any updates?

[superyyrrzz]

@mcm-ham @ipanin We are happy to merge pull requests for this.

[vad710]

Thank you, @mcm-ham - your solution worked for me. I just added the new files onto my existing template. It would be great to have this included in the default template.