Question

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

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

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

Answer 1

使用swagger-codegen：

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

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

从github
将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>的{{1}}应为<templates path>。

Answer 2

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

npm install spectacle-docs如果您想在package.json中添加脚本，或npm install -g spectacle-docs，如果它应该随处可用。

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

Answer 3

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

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

Answer 4

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

Answer 5

我一直在使用 OpenAPI Generator CLI Docker Image 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

Answer 6

＆＃34;静态＆＃34; docs可能意味着几件事。

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

codegen中执行更多静态文档的代码（没有＆＃34;现在尝试使用＆＃34;按钮）尚未针对2.0实现，但在未来几周内应该可用。

Answer 7

您可以使用：

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

Answer 8

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

它使用Maven生成静态文档，结果非常易读。它似乎具有高度的可配置性和可扩展性，但我尚未尝试过它。

Answer 9

单击预览文档，使用chrome插件“ Save Page WE”（在页面上单击鼠标右键->“保存页面we”），结果是单个html文件（不可点击，因此您必须单击想要的所有内容）看到）。

Answer 10

使用Spectacle的Docker image静态版本，在spec.json中（也可以在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

Answer 11

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

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

Answer 12

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

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

安装

转到https://github.com/swagger-api/swagger-ui/releases并以.zip文件下载最新版本。
解压缩文件，然后将 ./ dist 文件夹中的所有内容复制到您要提供网络服务器的目录中。例如，Gitlab Pages需要将其保存在存储库的 ./ public 文件夹中。
将您的 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/并签出！

Answer 13

在你的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>

尝试点击 - ＆gt; https://editor.swagger.io/

用swagger生成静态文档

13 个答案:

使用swagger-codegen：

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

安装

测试