用swagger生成静态文档

Question

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

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

到目前为止，我还没有办法做到这一点。我看到有swagger-codegens static-docs，但这只适用于swagger <= 1.2。

Answer 1

使用swagger-codegen：

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

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

1. 克隆来自github的swagger-codegen项目
2. 将modules/swagger-codegen/src/main/resources/htmlDocs2文件夹复制到另一个地方，例如：cp -R modules/swagger-codegen/src/main/resources/htmlDocs2 ~/templates
3. 修改.mustache中的~/templates模板以满足您的要求。
4. 运行：swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location> -t <templates path> for <templates path>应该是上面例子中的~/templates。

Answer 2

我通常用https://editor.swagger.io/做。无需安装或任何需要。

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

Answer 3

在你的pom中包含swagger的依赖。

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

Answer 4

如果您只想以简单的方式生成静态文档，请考虑Spectacle。

npm install spectacle-docs如果你想在你的package.json中放一个脚本，或者npm install -g spectacle-docs如果它应该随处可用。

然后你可以运行spectacle spec.yaml，可以选择构建到特定目录，运行服务器，和/或观察specfile并根据需要进行更新。

Answer 5

2.0中的static-docs是针对2.0实现的。请参阅此处的./bin/static-docs.sh：

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

Answer 6

如果你专门寻找Swagger 2.0，我想指出你在Converting Swagger specification JSON to HTML documentation的答案，虽然我相信Swagger-Codegen现在支持Swagger 2.0。

Answer 7

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

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

codegen中执行更多静态文档的代码（例如，没有“立即尝试”按钮）尚未针对2.0实现，但在未来几周内应该可用。

Answer 8

您可以使用：

• swagger-ui：只需git克隆项目并将JSON复制到基目录中
• swagger-codegen

Answer 9

我使用了这里描述的程序http://ics.upjs.sk/~novotnyr/blog/2156/create-html-documentation-from-swagger-via-maven。

它使用Maven生成静态文档，结果非常易读。它似乎是高度可配置和可扩展的，虽然我还没有尝试过。

Answer 10

点击预览文档，使用chrome addon'保存页面WE'（右键单击页面 - >'保存页面我们'），结果是单个html文件（它不可点击，所以你必须点击你想要看的所有内容）。

Answer 11

使用Spectacle的spec.json静态构建在Docker image（也可以在YAML中）中使用OpenAPI / Swagger规范可以生成如下：

mkdir -m 777 build && docker run --rm \
    -v `pwd`/build:/tmp/build \
    -v `pwd`/spec.json:/tmp/spec.json \
    sourcey/spectacle \
    spectacle -t /tmp/build /tmp/spec.json