New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

"exporting static HTML documentation" would be a great feature #664

Closed
kongfujianlong opened this Issue Sep 22, 2015 · 58 comments

Comments

Projects
None yet
@kongfujianlong

kongfujianlong commented Sep 22, 2015

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.

@mohsen1

This comment has been minimized.

Contributor

mohsen1 commented Sep 22, 2015

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

@dothebart

This comment has been minimized.

dothebart commented Sep 23, 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.

@dolmen

This comment has been minimized.

dolmen commented Sep 28, 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...

@lau235623

This comment has been minimized.

lau235623 commented Oct 5, 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

@kticka

This comment has been minimized.

kticka commented Oct 29, 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)

@vicaba

This comment has been minimized.

vicaba commented Nov 23, 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

@olivoil

This comment has been minimized.

olivoil commented Nov 23, 2015

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

@itayB

This comment has been minimized.

itayB commented Nov 24, 2015

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

@deefactorial

This comment has been minimized.

deefactorial commented Nov 28, 2015

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

@wweic

This comment has been minimized.

wweic commented Dec 12, 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.

@jurikolo

This comment has been minimized.

jurikolo commented Jan 6, 2016

+1 for exporting the html

1 similar comment
@op1ekun

This comment has been minimized.

op1ekun commented Jan 15, 2016

+1 for exporting the html

@JamesMGreene

This comment has been minimized.

JamesMGreene commented Jan 19, 2016

+1

@tommasop

This comment has been minimized.

tommasop commented Feb 12, 2016

+1

@bhougland

This comment has been minimized.

bhougland commented Feb 12, 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/

@tommasop

This comment has been minimized.

tommasop commented Feb 12, 2016

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 notifications@github.com 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:
#664 (comment)

@Deusdies

This comment has been minimized.

Deusdies commented Feb 29, 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.

@itayB

This comment has been minimized.

itayB commented Feb 29, 2016

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)

@anyong

This comment has been minimized.

anyong commented Mar 19, 2016

+1 for exporting the HTML

@isangomar

This comment has been minimized.

isangomar commented Apr 12, 2016

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

@Jeevi21

This comment has been minimized.

Jeevi21 commented Apr 12, 2016

+1 for downloading the doc as static HTML

@saharj saharj closed this Apr 13, 2016

@saharj

This comment has been minimized.

Contributor

saharj commented Apr 13, 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.

@JamesMGreene

This comment has been minimized.

JamesMGreene commented Apr 13, 2016

😢

@ChriWiChris

This comment has been minimized.

ChriWiChris commented Jul 15, 2016

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

  1. Open your YAML with swagger-editor in Chrome
  2. Right click on the preview pane and select "Inspect Element"
  3. In the HTML view look for the DOM-element<div ui-preview="preview">
  4. Right click on that element and select "Edit as HTML"
  5. Copy all the Code and Paste it into a new HTML file with html, header and body tags
  6. 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.

@itayB

This comment has been minimized.

itayB commented Jul 25, 2016

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:

  1. clone my forked repo: git clone http://github.com/itayB/swagger-editor.git
  2. cd swagger-editor
  3. npm install
  4. 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

@RobWin

This comment has been minimized.

RobWin commented Oct 25, 2016

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

@SGrondin

This comment has been minimized.

SGrondin commented Jan 7, 2017

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>

@fehguy

This comment has been minimized.

Contributor

fehguy commented Jan 7, 2017

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

@SGrondin

This comment has been minimized.

SGrondin commented Jan 7, 2017

@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".

@RobWin

This comment has been minimized.

RobWin commented Jan 7, 2017

@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

This comment has been minimized.

RobWin commented Jan 7, 2017

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

@RobWin

This comment has been minimized.

RobWin commented Jan 7, 2017

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

@fehguy

This comment has been minimized.

Contributor

fehguy commented Jan 7, 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

@dothebart

This comment has been minimized.

dothebart commented Jan 9, 2017

@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.

@marklagendijk

This comment has been minimized.

marklagendijk commented Jan 13, 2017

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();
     });
});
@twskj

This comment has been minimized.

twskj commented Feb 13, 2017

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

@therealsamlin

This comment has been minimized.

therealsamlin commented Apr 6, 2017

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

@SGrondin

This comment has been minimized.

SGrondin commented Apr 6, 2017

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

@weisd

This comment has been minimized.

weisd commented Aug 9, 2017

+1 for exporting the HTML

@burisk

This comment has been minimized.

burisk commented Oct 11, 2017

+1

@prashanthv

This comment has been minimized.

prashanthv commented Dec 7, 2017

+1 for exporting the HTML

@andrewcarretta

This comment has been minimized.

andrewcarretta commented Dec 14, 2017

+1

@rajaram87

This comment has been minimized.

rajaram87 commented Mar 1, 2018

+1 For exporting to html in 2018 😅

@phiner

This comment has been minimized.

phiner commented Mar 6, 2018

+1 for exporting to html

@rooftop90

This comment has been minimized.

rooftop90 commented Mar 7, 2018

+1

@Andiedie

This comment has been minimized.

Andiedie commented Mar 27, 2018

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.

@RonnieQuan

This comment has been minimized.

RonnieQuan commented May 18, 2018

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?

@Andiedie

This comment has been minimized.

Andiedie commented May 19, 2018

@relaxrq888 So sorry that it is only for 2.0.

@Charles-Gerber

This comment has been minimized.

Charles-Gerber commented Jun 4, 2018

+1 for exporting html documentation (for 3.0)

1 similar comment
@chinaxiaoyy

This comment has been minimized.

chinaxiaoyy commented Jun 8, 2018

+1 for exporting html documentation (for 3.0)

@v1adko

This comment has been minimized.

v1adko commented Aug 1, 2018

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.

@ohuseyinoglu

This comment has been minimized.

ohuseyinoglu commented Nov 4, 2018

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))

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment