Swagger-editor: "exporting static HTML documentation" would be a great feature

Created on 22 Sep 2015 · 63Comments · Source: swagger-api/swagger-editor

I really like the swagger YAML format and the HTML document generated by the swagger-editor. Actually, I really hope I can get a standalone HTML document, with exactly the same look as the one generated by the editor, but without the YAML editing part.

I understand there are other tools like swagger-codegen and swagger-to-markdown to generate static document. But the HTML document interactively generated by the editor is obviously a much better choice for a lot people:
(1) It's interactive, meaning easier to correct mistakes.
(2) The HTML generated is very user friendly, and based on my research, looks better than the static documents generated by other tools.
(3) Most importantly, it's easy to use and there is no need to deploy anything. For people like me who really just want to generate a tiny RESTful document it doesn't make sense to go through all the complicated tools.

Hence, I would really appreciate if swagger-editor can support exporting the interactively generated HTML document to a standalone HTML page, and I can ship to customer right away.

question

Source

kongfujianlong

👍69 ❤5

Most helpful comment

@SGrondin--wow. Consider joining the community effort by contributing code rather than just complaints. I bet everyone would appreciate that.

The language I used was strong. It's nice of you to remind me that we're all responsible for fixing what's broken, however, you might have noticed that there is a disconnect between how people use Swagger and how the tooling assumes people use Swagger.

I know for a fact I'm not the only one wary of investing time into this when it is very likely the contributions would not be welcomed. My rant is targeted, I list exactly what I think is broken and I suggest specific improvements. The first of which would be to acknowledge that this is a problem that can be fixed, instead of ignoring it.

Read the comments on this Issue and count the number of people suggesting ugly hacks due to the tooling being unfit. By refusing to reopen this issue, you're forcing the users to work _outside of the community_ and invent their own workarounds instead of investing that time into the Swagger project.

Until that happens, no one can "join the community effort by contributing code".

SGrondin on 7 Jan 2017

👍41

All 63 comments

You can add this to your branding.css file to hide anything but the preview

.total-wrapper > header,
.editor.pane,
.ui-splitbar,
[tooltip-popup],
.jump-to-yaml {
    display: none !important;
}

.preview.pane {
    position: fixed;
    left: 0 !important;
    top: 0 !important;
    right: 0 !important;
    width: 100% !important;
    height: 100% !important;
}

Swagger Editor preview pane is not designed to be a replacement of Swagger UI so the "hack" above is not officially supported. We will add more editor specific stuff to the right pane.

I've started a project based on this feedback for rendering Swagger documents in a nicer way. Check it out here: https://github.com/mohsen1/swagger-docs

mohsen1 on 22 Sep 2015

given the amount of time it takes swagger to render the ArangoDB Documentation, it would indeed cool if it could be pre-generated on the server, so the client doesn't have to do as much work.

dothebart on 23 Sep 2015

I really like the HTML rendering available in the editor (It is better for an overview and as a standalone documentation than swagger-ui), and I would appreciate an "export as HTML" feature (and/or a way to produce this rendering from a command line tool).

If the right pane could be rendered in separate browser window/tab, we could easily save it using browser UI functions...

dolmen on 28 Sep 2015

The modification of this 2 files do the similar trick that suit my needs.
Please feel free to use if that suit your needs as well.

Or use it @ http://io.api.zay-dev.com

Step 1. Replace the whole content of the index.html under the root directory with the following HTML

<!doctype html><head><meta charset="utf-8"><title>Swagger Editor</title><meta name="description" content="Swagger Editor"><meta name="viewport" content="width=device-width"><link rel="icon" type="image/png" href="./images/favicon-32x32.png" sizes="32x32"><link rel="icon" type="image/png" href="./images/favicon-16x16.png" sizes="16x16"><link rel="stylesheet" href="styles/main.css"><link rel="stylesheet" href="styles/branding.css"><body><div class="total-wrapper" ui-view></div><script src="scripts/vendor.js"></script><script src="scripts/scripts.js"></script><script src="scripts/branding.js"></script>
<script type="text/javascript">
    var PreviewWidth = 0,
        PreviewLeft = 0;

    function Download () {
        while (true) {
            var items = $(".json-schema-view.collapsed .toggle-handle"),
                length = items.length;
            if (length <= 0) break;
            else items.click();
        }
        $(".total-wrapper>header, main>.stretch>.editor, main>.stretch>.ui-splitbar, .all-tags").hide();

        PreviewWidth = $("main>.stretch>.preview").css("width");
        PreviewLeft = $("main>.stretch>.preview").css("left");
        $("main>.stretch>.preview").css({"width":"","left":""});

        var base64doc = btoa(unescape(encodeURIComponent(document.documentElement.innerHTML))),
            a = document.createElement('a'),
            e = document.createEvent("HTMLEvents");
        a.download = 'template.html';
        a.href = 'data:text/html;base64,' + base64doc;
        e.initEvent('click');
        a.dispatchEvent(e);
    }

    function RestoreFromDownload () {
        var items = $(".json-schema-view .toggle-handle"),
            length = items.length;
        items.click();

        $("main>.stretch>.preview").css({"width": PreviewWidth, "left": PreviewLeft});

        $(".total-wrapper>header, main>.stretch>.editor, main>.stretch>.ui-splitbar, .all-tags").show();
        PreviewWidth = 0;
        PreviewLeft = 0;
    }
</script>

Step 2. Replace the whole content of the header.html under views/header with the following HTML

<div class="main-header"><a href="http://swagger.io" target="_blank" class="logo" ng-if="!showHeaderBranding()"></a><div ng-include="'templates/branding-left.html'" ng-if="showHeaderBranding()" class="branding-3rdparty"></div><section class="menu-bar"><div class="file dropdown" ng-if="showFileMenu()"><button class="btn btn-default dropdown-toggle" ng-click="onFileMenuOpen()" data-toggle="dropdown" id="fileMenu"><span>File</span> <span class="caret"></span></button><ul class="dropdown-menu"><li><a dropdown-toggle ng-click="newProject()" tabindex="-1" track-event="file new">New</a></li><li><a dropdown-toggle id="open-example" ng-click="openExamples()" tabindex="-1" track-event="file open-example">Open Example&hellip;</a></li><li class="divider"></li><li><a dropdown-toggle ng-click="openPasteJSON()" tabindex="-1" track-event="file paste-json">Paste JSON&hellip;</a></li><li><a dropdown-toggle ng-click="openImportUrl()" tabindex="-1" track-event="file import url">Import URL&hellip;</a></li><li><a dropdown-toggle ng-click="openImportFile()" tabindex="-1" track-event="file import file">Import File&hellip;</a></li><li class="divider"></li>
<li><a href="#" class="download-html">Download HTML</a></li>
<li class="divider"></li>
<li><a download="swagger.yaml" data-downloadurl="{{yamlDownloadUrl}}" href="{{yamlDownloadHref}}" tabindex="-1" track-event="file download yaml">Download YAML</a></li><li><a download="swagger.json" downloadurl="{{jsonDownloadUrl}}" href="{{jsonDownloadHref}}" tabindex="-1" track-event="file download json">Download JSON</a></li></ul></div><div class="preferences dropdown"><button id="preferences" class="btn btn-default dropdown-toggle" data-toggle="dropdown"><span>Preferences</span> <span class="caret"></span></button><ul class="dropdown-menu"><li><a class="font-size">Font Size&nbsp; <span ng-click="adjustFontSize(1)" stop-event class="adjust" track-event="preferences font+">+</span><span ng-click="adjustFontSize(-1)" stop-event class="adjust" track-event="preferences font-">–</span></a></li><li><a dropdown-toggle ng-click="openEditorPreferences()" tabindex="-1" track-event="preferences settings">Editor Settings</a></li><li><a dropdown-toggle ng-click="resetSettings()" tabindex="-1" track-event="preferences reset-settings">Reset Editor Settings</a></li><li class="divider"></li><li><a dropdown-toggle tabindex="-1" ng-click="openPreferences()" track-event="preferences preferences">Preferences&hellip;</a></li></ul></div><!-- Handling of Code Generator service availability issues --><span class="text-danger dropdown-toggle" ng-if="serversNotAvailable">Server code generator is unreachable!</span> <span class="text-danger dropdown-toggle" ng-if="clientsNotAvailable">Client code generator is unreachable!</span><div class="dropdown" ng-if="servers && servers.length && !disableCodeGen"><button class="btn btn-default dropdown-toggle" data-toggle="dropdown" id="ServerMenu"><span>Generate Server</span> <span class="caret"></span></button><ul class="dropdown-menu"><li ng-repeat="server in ::servers track by $index"><a dropdown-toggle tabindex="-1" ng-click="getSDK('server', server)" track-event="generate-server {{server}}"><span class="name">{{capitalizeGeneratorName(server)}}</span> <span class="badge">Alpha</span></a></li></ul></div><div class="code-gen dropdown" ng-if="clients && clients.length && !disableCodeGen"><button class="btn btn-default dropdown-toggle" data-toggle="dropdown" id="ClientMenu"><span>Generate Client</span> <span class="caret"></span></button><ul class="dropdown-menu"><li ng-repeat="client in ::clients track by $index"><a dropdown-toggle tabindex="-1" ng-click="getSDK('client', client)" track-event="generate-client {{client}}"><span class="name">{{capitalizeGeneratorName(client)}}</span> <span class="badge">Alpha</span></a></li></ul></div><div class="help dropdown"><button class="dropdown-icon btn btn-default dropdown-toggle" id="helpMenu" data-toggle="dropdown"><span>Help</span> <span class="caret"></span></button><ul class="dropdown-menu"><li><a tabindex="-1" href="https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md" target="_blank">Swagger 2.0 Specs</a></li><li><a tabindex="-1" href="http://swagger.io/" target="_blank">Swagger Website</a></li><li><a dropdown-toggle tabindex="-1" ng-click="openAbout()">About Swagger Editor</a></li><li class="divider"></li><li><a href="https://github.com/swagger-api/swagger-editor/issues/new?labels=From%20Editor" target="_blank">Report A Bug</a></li><li class="divider"></li><li><a dropdown-toggle ng-click="toggleAboutEditor(true)" tabindex="-1">Show Introduction Help</a></li></ul></div></section><section class="status-bar"><div class="status {{statusClass}}" ng-if="status"><i ng-if="statusClass == 'working'" class="fa fa-spinner fa-pulse"></i> <i ng-if="statusClass == 'error'" class="fa fa fa-times"></i> <i ng-if="statusClass == 'success'" class="fa fa-check"></i> <span>{{status}}</span></div><div class="brandRight" ng-include="'templates/branding-right.html'" ng-if="showHeaderBranding()"></div></section></div>
<script type="text/javascript">
    var BindCount = 0;
    function BindDownloadOnclick () {
        BindCount++;
        $(".download-html").off("click").on("click", function () {
            Download();
            confirm("Press OK to restore page from download. But I don't think the cancel button will really cancel...");
            RestoreFromDownload();
        });

        console.log(BindCount);
        if (BindCount < 50) setTimeout(function () { BindDownloadOnclick(); }, 200);
    }
    BindDownloadOnclick();
</script>

[optional] Step 3. Copy the following folders into the desctination folder of the download:
/fonts
/styles

lau235623 on 5 Oct 2015

It would be awesome to split editor and preview to different windows. I'm working on two monitors, one would be for editing, another for preview. x)

kticka on 29 Oct 2015

I think that the editor pane for previsualizing html looks nicer than swagger ui. +1 for being able to export html from swagger-editor

vicaba on 23 Nov 2015

+1 export as html and/or option to display the preview without the editor and menu components would be nice

olivoil on 23 Nov 2015

+1 for exporting the html (preview of editor) for customers!

itayB on 24 Nov 2015

+1 for exporting the html view of the preview editor pane, the docs produced by the server ui are not as good.

deefactorial on 28 Nov 2015

The discrepancy between preview documentation and the one generated by swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l html -o /tmp/test/ is counter intuitive. It would be REALLY great if we could get the same look as preview's style for static HTML documentation.

wweic on 12 Dec 2015

👍14

if it help someone: http://stackoverflow.com/questions/34188440/swagger-ui-editor-like-page-add-to-my-web-site/34308338#34308338

itayB on 20 Dec 2015

+1 for exporting the html

jurikolo on 6 Jan 2016

+1 for exporting the html

op1ekun on 15 Jan 2016

JamesMGreene on 19 Jan 2016

tommasop on 12 Feb 2016

This helped me: https://github.com/nknapp/bootprint-openapi

Also, check out this link to his bootprint-openapi playground...just paste your YAML file and view generated HTML doc: https://bootprint.knappi.org/

bhougland on 12 Feb 2016

👍2

Thanks for your suggestion, I've already used it and is very nice, still I think it would be "natural" to have an export to HTML directly in the editor.

Il giorno 12 feb 2016 22:49, alle ore 22:49, Benson Hougland [email protected] ha scritto:

This helped me: https://github.com/nknapp/bootprint-openapi

Also, check out this link to his bootprint-openapi playground...just
paste your YAML file and view generated HTML doc:
https://bootprint.knappi.org/

Reply to this email directly or view it on GitHub:
https://github.com/swagger-api/swagger-editor/issues/664#issuecomment-183500914

tommasop on 12 Feb 2016

One of the main reasons I started using Swagger editor was because I saw how beautiful the documentation part of the editor looked like in the online demo. I must say I'm disappointed that you cannot export that (I was hoping for even an "Export as PDF" option). For now, generating a static HTML client will do.

Deusdies on 29 Feb 2016

👍8

If you want to save it as PDF, you can print as pdf in chrome (just hide the editor section by clicking on the middle border and drag it to left). BTY this approche might be workaround to use this UI without the editor (and of course, hide the upper menu -all with js)

itayB on 29 Feb 2016

+1 for exporting the HTML

anyong on 19 Mar 2016

+1 get swagger editor preview window, into static html files for easy hosting.

isangomar on 12 Apr 2016

👍1

+1 for downloading the doc as static HTML

Jeevi21 on 12 Apr 2016

Sorry but we have no plans to do this.

If you're interested, you can make a static Swagger documents renderer using this project's HTML/CSS in Swagger Code-Gen Project, then Swagger Editor will show it in Generate Client section.

saharj on 13 Apr 2016

👎103 😕9

:cry:

JamesMGreene on 13 Apr 2016

😕4

+1 to exporting as HTML

nachoco on 28 Jun 2016

+1 for the really much better layout in the editor preview than the generated swagger-ui.

I think it's not that important to export static HTML pages but to be able to use different layouts for dynamically generated swagger.json specs. The layout in swagger-ui has a lot of disadvantages in comparison to the layout of the editor preview pane.

ChriWiChris on 8 Jul 2016

👍3

@ChriWiChris - can you elaborate on the disadvantages?

webron on 8 Jul 2016

Sure. I compare the petstore in swagger-ui (SUI) to the petstore in swagger-editor (SE):

The headlines in SE are way more precise. I find "summary" and "description" instead of "implementation notes" in SUI. Also I find a schema in the response insted of a Response Class (in json there are no classes).
The ordering of elements in SE is much more intuitive since the request params are always on top of the response and its description. In SUI there is a response class on top of the request params which is confusing.
For the testing of endpoints via the frontend SE has a separate section, that only opens if the user hits the Try It Out Button. In SUI there are the input fields in the documentation which is a bit messy and in case of disabled Try It Out Button confusing.
The Description of single attributes in the response message is in SE directly when clicking on the object (like "String" or something").

In my opinion this makes SE a more user-friendly API documentation than SUI. As a developer consuming public APIs it is important to have the best documentation about everything that deals with that API, so SE is much more preferable.

ChriWiChris on 12 Jul 2016

👍10

Thanks for the detailed explanation, that helps us in evaluating future changes.

webron on 13 Jul 2016

By the way: if you want to export the preview pane of swagger-editor in a static HTML page, do the following:

Open your YAML with swagger-editor in Chrome
Right click on the preview pane and select "Inspect Element"
In the HTML view look for the DOM-element<div ui-preview="preview">
Right click on that element and select "Edit as HTML"
Copy all the Code and Paste it into a new HTML file with html, header and body tags
Link to the swagger-editor stylesheet with <link rel="stylesheet" media="all" href="http://editor.swagger.io/dist/styles.css"></link>

Now you have your docs in a static html file. The only thing you need to do is to write some JavaScript to get the toggling of the operations etc. working.

ChriWiChris on 15 Jul 2016

😄6 👍5 ❤3 🎉3

I've add a short dirty workaround for previewing only the relevant section of the swagger-editor. You can see the changes here.
You can try it:

clone my forked repo: git clone http://github.com/itayB/swagger-editor.git
cd swagger-editor
npm install
npm start

Please note: This preview shows the output of the file spec-files/default.yaml.
I've only made some view changes, all the editor logic is still running behind.

Cheers

itayB on 25 Jul 2016

👍3

As an alternative, you could have a look at https://github.com/Swagger2Markup/swagger2markup

RobWin on 25 Oct 2016

UPDATE: https://github.com/Rebilly/ReDoc solved my problem beautifully.

It's mind boggling that @ChriWiChris 's hack is the best (rather, the least terrible) way to generate static documentation.

swagger-codegen -l html looks awful, the result is not user friendly at all and injects links to helloreverb.
swagger-codegen -l dynamic-html looks awful, the result is not user friendly at all and requires me to run a Node process to serve STATIC DOCUMENTATION. How does this make any sense?
swagger-ui is not user friendly. For these reasons plus:
- The grouping by tags is counter-intuitive. Paths are duplicated if they have more than one tag. The Swagger-Editor does it right.
- docExpansion should be list by default. Otherwise, users are greeted by a list of tags that don't immediately make sense.
- defaultModelRendering should be model. The example is more confusing than helpful.
- validatorUrl should probably be null by default, this is for visualizing an API, not validating or editing it. I don't want a dependency on the online validator.
- Let me disable the Parameter "Value" column! I don't want to make requests, I want to VISUALIZE an API. The Value column takes up a lot of horizontal space and does nothing except confuse users. Give me an option to disable it without having to resort to custom JavaScript to delete it!

I can kinda work around Swagger-UI's issues by only having a single tag per path and setting a few options, but it's still light years behind the user friendliness of the Editor.

I'm far from the only user interested in using Swagger for documentation purposes. I don't care about Swagger's apparent obsession for code generation. I'm honestly tempted to direct users to the Editor and ask them to load from Url and just use that to visualize... or to fork the Editor directly.

I don't want to run a server. I don't want it to look like 90s Javadoc. Ugly looking docs don't get read. Docs don't have to be beautiful, but they can't be ugly.

</rant>

SGrondin on 7 Jan 2017

👍19

@SGrondin--wow. Consider joining the community effort by contributing code rather than just complaints. I bet everyone would appreciate that.

fehguy on 7 Jan 2017

👎14

@SGrondin--wow. Consider joining the community effort by contributing code rather than just complaints. I bet everyone would appreciate that.

Until that happens, no one can "join the community effort by contributing code".

SGrondin on 7 Jan 2017

👍41

@sgrondin Did you try https://github.com/Swagger2Markup/swagger2markup for you use case? There are Maven/Gradle plugins, a CLI and a Docker Image and template projects available which show how to use it. I think the documentation is also good.

RobWin on 7 Jan 2017

You can generate HTML, PDF and EPUB from your Swagger Spec by converting it into Asciidoctor and then run the Asciidoctor plugin.

RobWin on 7 Jan 2017

You could also just generate Markdown and use a static site generator which support Markdown to create your own custom HTML documentation.

RobWin on 7 Jan 2017

Sorry @SGrondin, you're being an ass about this. I think you're missing the whole point of OSS--consider @RobWin's suggestion and good luck

fehguy on 8 Jan 2017

👎23 😕4

@fehguy I guess you get that sort of harsh critism if you close such a feature request in a way that @saharj did. And its definitely not encuraging contributions.

dothebart on 9 Jan 2017

👍22

You can customize the index.html and add custom javascript or css (either inline or externaly).
With the following css you can hide the editor and make the viewer full screen:

.pane.editor, .ui-splitbar{
    display: none;
}

.pane.preview{
    left: 0 !important;
    width: 100% !important;
}

With the following javascript you can start with the editor closed, but still have the ability to open it:

SwaggerEditor.run(function($timeout){
     $timeout(function(){
         document.getElementsByClassName('ui-splitbar-icon-left')[0].click();
     });
});

marklagendijk on 13 Jan 2017

I wrote a tool to generate a similar looking page. Some of you might find it useful.
https://twskj.github.io/pretty-swag/

twskj on 13 Feb 2017

👍9 🎉4 ❤2

@saharj Any explanation on why there are no plans of doing this? It'll make all swagger users life easier

therealsamlin on 6 Apr 2017

👍7

I'd suggest to anyone following this issue to simply use the (very nice and clean) https://github.com/Rebilly/ReDoc instead.

SGrondin on 6 Apr 2017

👍14

+1 for exporting the HTML

weisd on 9 Aug 2017

burisk on 11 Oct 2017

+1 for exporting the HTML

prashanthv on 7 Dec 2017

andrewcarretta on 14 Dec 2017

+1 For exporting to html in 2018 :sweat_smile:

rajaram87 on 1 Mar 2018

👍2

+1 for exporting to html

phiner on 6 Mar 2018

rooftop90 on 7 Mar 2018

👍2

There's a temporary solution.

Install

Actually, there's only one html file.
Download this static.zip and unzip it.

Usage

Just double click static.html!

You can either open static.html through a file:// protocol or access it under a static file server.

file://path/to/static.html
http://example.com/static.html

Config

This html uses A Example Yaml by default.

You can customize the yaml file by adding a query url:

file://path/to/static.html?url=http://example.com/your.yaml
http://example.com/static.html?url=http://example.com/your.yaml

Or you can just change url field on the line 359 in static.html (almost at the end) to your yaml link.

Andiedie on 27 Mar 2018

👍9 ❤2

I have tried using static.html to open an open API 3.0 yaml doc, but got an error, No operations defined in spec!
Does this temporary solution support open API 3.0 doc?

RonnieQuan on 18 May 2018

@relaxrq888 So sorry that it is only for 2.0.

Andiedie on 19 May 2018

+1 for exporting html documentation (for 3.0)

Charles-Gerber on 4 Jun 2018

+1 for exporting html documentation (for 3.0)

chinaxiaoyy on 8 Jun 2018

👍1

Hey people.
I've had the same confusion when I started using Swagger Editor.
Combined and updated some of the suggestions and "hacks" to make it work.
The setup is minimal, all that's needed is static HTML file and your YAML/JSON config.

It worked for me and maybe it's gonna work for some of your use cases.
You can take a look at the result here
And the code is here.

Solution is very similar to @Andiedie approach as it turned out, but with less inline styles.
And it seems to work with OpenAPI 3.0, just not sure to what extent.

v1adko on 1 Aug 2018

👍3

As an addendum to htmls provided by @Andiedie, and @v1adko in comments above (in case you do not want to or cannot export your YAML spec on an HTTP server, or have a CORS problem b/w the server with static.html, and your YAML): Keep in mind that there is also the option of taking care of everything in a single file:

Convert your YAML spec to JSON by either using the http://editor.swagger.io, or the swagger-codegen-cli (with language swagger)
And then embed that JSON text as the spec parameter/field of the "SwaggerEditorBundle" / "SwaggerUIBundle" (depending on the version you use).

(While making your documentation offline-available/portable, you may also want to consider setting validatorUrl parameter to null to avoid a round-trip to swagger validator service (and possible leak of your API))