27

I have created a Swagger documentation with a yaml file under:

api/swagger/swagger.yaml

Now I want to share a static HTML document with its definition, yet it was stated on the swagger project, that they don't plan to support HTML generation at all.

How can I generate a static HTML file from a Swagger project?

2240
  • 1,547
  • 2
  • 12
  • 30
k0pernikus
  • 60,309
  • 67
  • 216
  • 347

6 Answers6

25

The easiest way I can think of is to use Swagger Editor:

  1. Go to: https://editor.swagger.io
  2. Click on "File" in the top menu bar and then select "Import File"
  3. After import, click on "Generate Client" in the top menu bar, and then select "HTML" or "HTML2" to generate static HTML documentation

editor.swagger.io uses generator.swagger.io to generate API clients, server stubs and documentation, and generator.swagger.io is powered by the open-source project Swagger Codegen.

k0pernikus
  • 60,309
  • 67
  • 216
  • 347
William Cheng
  • 10,137
  • 5
  • 54
  • 79
12
  1. Download https://github.com/swagger-api/swagger-ui - folder of interest is "dist"
  2. Copy your Swagger JSON into the dist folder
  3. Open index.html and change the value of URL inside the tag at the bottom of the file to ./swagger.json (or whatever your swagger json is called) (see here)
  4. Host online! (or start a local server to view output).
Ismail Moghul
  • 2,864
  • 2
  • 22
  • 28
4

There is swagger2markup-cli that can generate a static adoc file.

Ensure that you have Java runtime installed. (I am using Java(TM) SE Runtime Environment (build 1.8.0_111-b14)).

You fetch the jar:

wget https://jcenter.bintray.com/io/github/swagger2markup/swagger2markup-cli/1.1.0/swagger2markup-cli-1.1.0.jar

And you can generate the a static adoc with it via:

java -jar ~/your/path/swagger2markup-cli-1.1.0.jar convert  -i api/swagger/swagger.yaml --outputFile static-swagger

That adoc file can then be converted into a html file via asciidoctor:

asciidoctor *.adoc

You may need to install it, as I am using Ubuntu, I could via:

sudo apt-get -qq install asciidoctor
2240
  • 1,547
  • 2
  • 12
  • 30
k0pernikus
  • 60,309
  • 67
  • 216
  • 347
  • This solution works for me, just a few notes: the generated pages are not hyperlinked, they're just simple HTML pages with no frames. asciidoctor is Ruby dependent. – Michal Špondr Oct 29 '18 at 07:04
2

Are you trying to export it to create single documentation from different services? If yes, an alternative might be https://github.com/varghgeorge/microservices-single-swagger. This simple springboot microservice will show all your swagger documentation (from different servers) in one place based on YAML config.

George
  • 81
  • 2
  • 5
0

Another answer suggested the Swagger Editor , which is great. However, to obtain a single file to import into it:

  1. npm install -g @apidevtools/swagger-cli
  2. swagger-cli bundle openapi.yaml --outfile ./openapi-expanded.json --type json

The above command assumes your root file is named openapi.yaml and you want an output JSON file openapi-expanded.json: that JSON is what you'll import.

payne
  • 4,691
  • 8
  • 37
  • 85
0

Use an HTML file like this to load your OpenAPI definition:

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" type="text/css" href="//unpkg.com/swagger-ui-dist@3/swagger-ui.css">

  <title>Your App API v1</title>

<body>

  <div id="your-app-docs" />

  <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
  <script>

    window.onload = function () {

      const ui = SwaggerUIBundle({
        url: "openapi.yml",
        dom_id: "#your-app-docs",
        deepLinking: true,
      })

    }

  </script>

</body>

</html>

You can then later host it locally or use a service like Netlify to host it on the web.

Louis Huang
  • 589
  • 3
  • 7