Interactive HTML Documentation

[mhailstone]

Description

We would like to use only the “preview” frame of the swagger-editor as our static html documentation instead of the current static html in the swagger-codegen. I would like to propose a new generator that exports just the preview frame html with the needed supporting CSS or javascript to expand/collapse the paths, operations, and model definitions.

[jimschubert]

@mhailstone This might be a dumb question, but are you aware of the swagger-ui project?
You can see an example of developer documentation provided by Swagger UI here: http://petstore.swagger.io/#!/pet/updatePet

Download links and all are available here: http://swagger.io/swagger-ui/

Or are you looking for something somewhere in between the current html generator and Swagger UI? The UI of swagger editor also has a "try this operation" similar to Swagger UI. The editor's preview also has lots of links to jump from models to references in the yaml being edited, which is fairly different from how models are documented in Swagger UI.

[mhailstone]

@jimschubert We did look at the swagger-ui project, but we really liked just the preview frame layout in the swagger-editor project. We intend to render the page in static html for documentation purposes on a Developer Portal site, but we don't need the "Try this operation" feature-like interaction. That is why we liked the layout and view of the "preview" frame in the editor (above the "Try this operation" button).

The current static html that in generated in the swagger-codegen project is a different look and feel than we would like also, so that is why I'm wondering if those who are familiar with the "preview" frame in the swagger-editor project could create a codegen generator that could spit out the "preview" frame type view without the "Try this operation". That upper portion HTML layout is complete and interactive enough as a static page that could be used as documentation in our Developer Portal outside of the "Try this operation" functionality that we are gaining when developers are directed to our WSO2 store. Let me know if this is still unclear. Thanks for the response and suggestion to the swagger-ui project, though.

[jimschubert]

Yeah, that makes more sense.

Have you attempted to run swagger-editor and disable some options? It's not static, but it would give you a configurable instance with the added benefit that you can pull upstream bug fixes.

Another option might be to use the template-dir option for swagger codegen:

        -t <template directory>, --template-dir <template directory>
            folder containing the template files

This allows you to set a directory containing these templates: https://github.com/swagger-api/swagger-codegen/tree/master/modules/swagger-codegen/src/main/resources/htmlDocs

You could then tweak the mustache templates used for generation to your needs. The script that builds the samples in the sample directory is here.

Following this method, you could add branding, links or whatever and it would be repeatable.

[mhailstone]

@jimschubert Thanks for the suggestions. We will look into the template option.

[kadosh1000]

Hi,
I am facing the same issue. I want as well to generate a static html page which is the same as the Swagger Editor preview html. @mhailstone have you found a way to do that?

[mhailstone]

@kadosh1000 We have not yet. Interestingly enough, today we just decided to research how we might run the swagger-editor project as an AWS service to return just the preview html portion on a request. If we find a decent solution, I'll definitely share. Thanks for posting.

[wing328]

@mhailstone @kadosh1000 there's a new HTML documentation generator html2 contributed by @jhitchcock: #3447

Please pull the latest master and give it a try.

Please let me know if there's any issues or questions with html2!

[larskoeie]

@jhitchcock Wow! htmlDocs2 is so much prettier than htmlDocs. Thanks.