将 Swagger 规范 JSON 转换为 HTML 文档

对于一些用 PHP 编写的 REST API，我被要求创建 斯威格文档，因为我不知道有什么简单的方法可以将注释添加到那些现有的 API 并创建这样的文档，所以我暂时使用 这个编辑来生成一些文档。

我保存了使用该编辑器创建的 JSON 和 YAML 文件，现在需要创建最终的交互式 Swagger 文档(这个语句可能听起来很幼稚和模糊)。

有人能告诉我如何将 Swagger JSON 规范文件转换成真正的 Swagger 文档吗？

我使用的是 Windows 平台，对 Ant/Maven 一无所知。

180668 次浏览
小开

Give a look at this link : http://zircote.com/swagger-php/installation.html

  1. Download phar file https://github.com/zircote/swagger-php/blob/master/swagger.phar
  2. Install Composer https://getcomposer.org/download/
  3. Make composer.json
  4. Clone swagger-php/library
  5. Clone swagger-ui/library
  6. Make Resource and Model php classes for the API
  7. Execute the PHP file to generate the json
  8. Give path of json in api-doc.json
  9. Give path of api-doc.json in index.php inside swagger-ui dist folder

If you need another help please feel free to ask.

小开

See the swagger-api/swagger-codegen project on GitHub ; the project README shows how to use it to generate static HTML. See Generating static html api documentation.

If you want to view the swagger.json you can install the Swagger UI and run it. You just deploy it on a web server (the dist folder after you clone the repo from GitHub) and view the Swagger UI in your browser. It's a JavaScript app.

小开
最佳答案

I was not satisfied with swagger-codegen when I was looking for a tool to do this, so I wrote my own. Have a look at bootprint-swagger

The main goal compared to swagger-codegen is to provide an easy setup (though you'll need nodejs). And it should be easy to adapt styling and templates to your own needs, which is a core functionality of the bootprint-project

小开

Check out pretty-swag

It has

  1. Similar looking as Swagger-Editor's right panel
  2. Search / Filter
  3. Schema Folding
  4. Live Feedback
  5. Output as a single html file

I was looking at Swagger Editor and thought it could export the preview pane but turned out it cannot. So I wrote my own version of it.

Full Disclosure: I am the author of the tool.

小开

You can also download swagger ui from: https://github.com/swagger-api/swagger-ui, take the dist folder, modify index.html: change the constructor 

const ui = SwaggerUIBundle({
url: ...,

into

const ui = SwaggerUIBundle({
spec: YOUR_JSON,

now the dist folder contains all what you need and can be distributed as is

小开

Everything was too difficult or badly documented so I solved this with a simple script swagger-yaml-to-html.py, which works like this

python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html

This is for YAML but modifying it to work with JSON is also trivial.

小开

I spent a lot of time and tried a lot of different solutions - in the end I did it this way :

<html>
<head>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3.17.0/swagger-ui.css">
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<script>


function render() {
var ui = SwaggerUIBundle({
url:  `path/to/my/swagger.yaml`,
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
]
});
}


</script>
</head>


<body onload="render()">
<div id="swagger-ui"></div>
</body>
</html>

You just need to have path/to/my/swagger.yaml served from the same location.
(or use CORS headers)

小开

Try to use redoc-cli.

I was using bootprint-openapi by which I was generating a bunch of files (bundle.js, bundle.js.map, index.html, main.css and main.css.map) and then you can convert it into a single .html file using html-inline to generate a simple index.html file.

Then I found redoc-cli very easy to to use and output is really-2 awesome, a single and beautiful index.html file.

Installation:

npm install -g redoc-cli

Usage:

redoc-cli bundle -o index.html swagger.json
小开

There's a small Java program which generates docs (adoc or md) from a yaml file.

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withSwaggerMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.DE)
.build();


Swagger2MarkupConverter builder = Swagger2MarkupConverter.from(yamlFileAsString).withConfig(config).build();
return builder.toFileWithoutExtension(outFile);

Unfortunately it only supports OpenAPI 2.0 but not OpenAPI 3.0.

小开

For Swagger API 3.0, generating Html2 client code from online Swagger Editor works great for me!

小开

If you commit your JSON file in Gitlab, it will render it for you.

小开

Redocly's CLI interface has a tool to build HTML docs from OpenAPI spec files.

sudo npm i -g @redocly/cli
redocly build-docs my-swagger.yml -o docs.html

提交答案