大张旗鼓地生成静态文档

Question 1

有没有为swagger 2.0创建静态文档的方法？也许就像editor.swagger.io上的“预览”。

我需要获取静态html文件，以便可以将它们包含在某些静态文档中。

到目前为止，我还没有找到一种方法来执行此操作。我看到有swagger-codegens静态文档，但这仅适用于swagger <= 1.2。

Question 2

使用swagger-codegen：

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

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

从github克隆swagger-codegen项目
将modules/swagger-codegen/src/main/resources/htmlDocs2文件夹复制到另一个位置，例如：cp -R modules/swagger-codegen/src/main/resources/htmlDocs2 ~/templates
修改.mustache模板~/templates以适合您的要求。
运行：swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location> -t <templates path>for<templates path>应该~/templates在上面的示例中。

Question 3

如果您只想直接生成静态文档，请考虑使用Spectacle。

npm install spectacle-docs如果您要在中放置脚本package.json，或者该脚本npm install -g spectacle-docs应随处可用。

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

Question 4

2.0中的static-docs是为2.0实现的。请在此处查看./bin/static-docs.sh：

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

Question 5

您可以使用：

swagger-ui：只需git克隆项目，然后将您的JSON复制到基本目录中
昂扬的代码

Question 6

您可以swagger-codegen像其他人提到的那样使用该命令，但是从使用中获得的输出-l html或-l html2与Swagger UI一样不是交互式的。

要获得交互式的静态页面（如Swagger UI），请按照以下步骤操作：

安装

转到https://github.com/swagger-api/swagger-ui/releases并以.zip文件下载最新版本。
解压缩该文件，然后将./dist文件夹中的所有内容复制到要提供Web服务器的目录中。例如，Gitlab Pages需要将其放在存储库中的./public文件夹中。
你copy过来swagger.yml文件到./public文件夹。
打开./public/index.html文件，并将URL更新为swagger文件在Web服务器上的位置。对于本地服务器，可能是这样的：url: "http://localhost:8000/swagger.yml

测试

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

python3 -m http.server 8000 --directory public

打开http：// localhost：8000 /并签出！

Question 7

如果您专门寻找Swagger 2.0，尽管我相信Swagger-Codegen目前支持Swagger 2.0，但我还是想向您提供将Swagger规范JSON转换为HTML文档中的答案。

Question 8

我通常使用https://editor.swagger.io/进行操作。无需安装或需要任何东西。

将您的yml文件复制到编辑器中，然后选择“生成客户端> html2”，它将在zip文件中生成静态html文件。

Question 9

“静态”文档可能意味着几件事。

如果您正在寻找交互式显示（例如编辑器的预览），则可以使用swagger-ui（https://github.com/swagger-api/swagger-ui）。

虽然在接下来的几周内将提供2.0版本的代码，但尚未实现更多静态文档的代码生成代码（例如，没有“立即尝试”按钮）。

Question 10

我已使用此处描述的过程http://ics.upjs.sk/~novotnyr/blog/2156/create-html-documentation-from-swagger-via-maven。

它使用Maven生成静态文档，并且结果可读性强。尽管我还没有尝试过，但它似乎是高度可配置和可扩展的。

Question 11

单击预览文档，使用chrome插件“保存页面WE”（右键单击页面->“保存页面我们”），结果是单个html文件（不可点击，因此您必须单击想要显示的所有内容）。

Question 12

OpenAPI 3

要将OpenAPI 3规范呈现为独立的HTML文件，可以使用redoc-cli。您可以使用ReDoc的Petstore 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根据自己构建一个Docker映像Dockerfile，或者在其中安装redoc-cliNodeJS的情况下安装到您的OS。npm install -g redoc-cli。

OpenAPI 2

ReDoc还具有OpenAPI 2 / Swagger的兼容模式，因此以上内容也适用于Petstore OpenAPI 2规范。

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

另外，还有仅OpenAPI 2的Spectacle及其官方Docker映像。可以类似使用：

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

Question 13

在pom中包括对招摇的依赖。

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