“静态”文档可以有几种含义。

如果您正在寻找交互式显示(比如编辑器预览) ，那么您可以使用 swagger-ui (https://github.com/swagger-api/swagger-ui)。

编码器中用于处理更多静态文档的代码(例如，没有“立即尝试”按钮)尚未在2.0中实现，不过应该在未来几周内就可以使用。

2.0中的 static-docs 是为2.0实现的:

Https://github.com/swagger-api/swagger-codegen/tree/master/bin

如果你特别想找斯威格2.0我想告诉你我的答案 将 Swagger 规范 JSON 转换为 HTML 文档 尽管我相信 Swagger-Codegen 现在已经支持斯威格2.0了。

使用夸张代码:

swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location>

如果您决定自定义 HTML 模板:

1. 从 Github中克隆大摇大摆编码项目
2. 将 modules/swagger-codegen/src/main/resources/htmlDocs2文件夹复制到另一个位置，例如: cp -R modules/swagger-codegen/src/main/resources/htmlDocs2 ~/templates
3. 修改 ~/templates中的 .mustache模板以满足您的需求。
4. 运行: 在上面的例子中，<templates path>的 swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location> -t <templates path>应该是 ~/templates。

如果您只想以一种简单的方式生成静态文档，可以考虑使用 太壮观了。

如果你想把一个脚本放在你的 package.json，或者 npm install -g spectacle-docs，如果它应该可以在任何地方。

然后，您可以只运行 spectacle spec.yaml，其中包含构建到特定目录、运行服务器和/或监视规范文件并根据需要进行更新的选项。

你可使用:

• Swagger-ui : 只需要 git 克隆项目并将 JSON 复制到基本目录中
• 狂妄自大的代码

在你的诗歌中包含对自信的依赖。

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>

试着击打-> https://editor.swagger.io/

点击预览文档，使用 chrome 插件“保存页面我们”(右键点击页面-> “保存页面我们”) ，结果是单一的 html 文件(它不能点击，所以你必须点击你想要看到的一切)。

OpenAPI 3

为了将 OpenAPI 3规范呈现为自包含的 HTML 文件，可以使用 Redoc-cli。您可以使用 ReDoc 的 宠物店 OpenAPI 3规范作为示例。

mkdir -p -m 777 build && docker run --rm --user 1000 \
-v $PWD/build:/tmp/build -w /tmp/build \
-v $PWD/openapi.yaml:/tmp/openapi.yaml node:14-slim npx -q \
redoc-cli bundle /tmp/openapi.yaml

这将在你的工作目录中生成 build/redoc-static.html。

为了避免等待安装，您还可以使用 redoc-cli根据它们的 Dockerfile构建自己的 Docker 映像，或者使用 npm install -g redoc-cli在操作系统上安装 redoc-cli(如果有 NodeJS 的话)。

OpenAPI 2

ReDoc 还有 OpenAPI 2/Swagger 的兼容模式，所以上面的也适用于 宠物店 OpenAPI 2规范。

[ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0

另外，还有 OpenAPI 2-only Spectacle 和它的官方 码头形象。它可以像下面这样使用:

mkdir -p -m 777 build && docker run --rm --user 1000 \
-v $PWD/build:/tmp/build \
-v $PWD/swagger.yaml:/tmp/swagger.yaml sourcey/spectacle \
spectacle -t /tmp/build /tmp/swagger.yaml

它生成的静态构建几乎是自包含的(除了从 code.jquery.com加载 jQuery，因为某些原因在我这里比较慢)。

├── index.html
├── javascripts
│   ├── spectacle.js
│   └── spectacle.min.js
└── stylesheets
├── foundation.css
├── foundation.min.css
├── spectacle.css
└── spectacle.min.css

我通常使用 https://editor.swagger.io/来完成，不需要安装或者任何需要的东西。

将 yml 文件复制到编辑器中，并选择“ Generate Client > html2”，它将在 zip 文件中生成静态 html 文件。

可以像其他人提到的那样使用 swagger-codegen命令，但是使用 -l html或 -l html2得到的输出不像 Swagger UI 那样具有交互性。

要获得类似 Swagger UI 的 互动静态页面，请按照以下步骤操作:

安装

• 转到 https://github.com/swagger-api/swagger-ui/releases并以. zip 文件的形式下载最新版本。
• 解压文件并将 。/dist文件夹中的所有内容复制到您希望 webserver 提供的目录中。例如，Gitlab Pages需要放在存储库中的 文件夹中。
• 将 大摇大摆文件复制到 文件夹。
• 打开。/public/index.html 文件，并将 URL 更新为 swagger 文件在 webserver 上的位置。对于本地服务器，它可能是这样的: url: "http://localhost:8000/swagger.yml

测试

要测试这一点，您可以使用 python3运行一个简单的 HTTP 服务器。

python3 -m http.server 8000 --directory public

打开 http://localhost:8000/检查一下！

我一直在使用 OpenAPI 生成器 CLI Docker 图像 https://github.com/OpenAPITools/openapi-generator

它可以生成服务器、客户端和文档。对于每种语言，都有模板文件，因此您可以根据需要修改行为

我设法获得了一个 Python-flask 服务器生成和自托管生成的文档。

下面将生成一个包含客户端代码示例的 html 文件

USER=$(shell id -u)
GROUP=$(shell id -g)
MDIR=$(shell pwd)


docker run --rm --user ${USER} -u\:${GROUP} \
-v ${MDIR}:/local openapitools/openapi-generator-cli generate \
--package-name EXAMPLE \
-t /local/.openapi-generator-html-client/ \
-i /local/EXAMPLE.v1.yaml \
-g html2 \
-o /local/openapi_docs