使用Swagger生成静态文档

Question

使用Swagger生成静态文档

86

有没有一种方法可以创建Swagger 2.0的静态文档？类似于editor.swagger.io上的“preview”。我需要得到静态HTML文件，以便将其包含在某些静态文档中。到目前为止，我还没有找到一种方法来实现这一点。我看到了swagger-codegen的static-docs，但这仅适用于Swagger<=1.2。

- romeovs

13个回答

21

如果您只想简单生成静态文档，可以考虑使用Spectacle。

如果您想将脚本放入package.json中，可以执行npm install spectacle-docs；如果您想让它在任何地方都可用，请执行npm install -g spectacle-docs。

然后，您只需要运行spectacle spec.yaml，并进行相关设置（例如，指定生成目录、运行服务器、监视规范文件并根据需要更新等）。

- Will

请原谅初学者的问题，什么是spec.yaml？它可以由Swagger生成吗？在我的情况下，我只有由Spring管理的Java端点上的注释，并且Swagger页面神奇地出现了。谢谢您的帮助！ - chrisinmtown

@chrisinmtown spec.yaml 指的是 Swagger 规范本身，可以用 JSON 或 YAML 语法表示。 - Charlie Reitzel

4

看起来这个项目已经停止开发，并且不支持 OpenAPI 3.0。 - lssilva

哦，谢谢，你不知道我有多想知道是哪个工具构建了这些文档 o/。你知道我们是否可以使用Spectable添加代码示例吗？ - TalesMGodois

10

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

要获取类似Swagger UI的交互式静态页面，请按照以下步骤操作：

安装

前往https://github.com/swagger-api/swagger-ui/releases下载最新版本的.zip文件。
解压文件并将./dist文件夹中的所有内容复制到您想要网页服务器提供服务的目录中。例如，对于Gitlab Pages，它需要在存储库的./public文件夹中。
将您的swagger.yml文件复制到./public文件夹中。
打开./public/index.html文件并更新URL，使其指向位于网页服务器上的Swagger文件位置。对于本地服务器，它可能是这样：url: "http://localhost:8000/swagger.yml"

测试

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

python3 -m http.server 8000 --directory public

在浏览器中打开http://localhost:8000/查看效果！

- jasonrhaas

6

OpenAPI 3

要将OpenAPI 3规范呈现为自包含的HTML文件，可以使用redoc-cli。您可以使用ReDoc的Petstore OpenAPI 3 spec作为示例。

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。

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

更新： 实际上，在项目的 GitHub Docker registry 中有一个预构建的 Docker 镜像，例如 ghcr.io/redocly/redoc/cli:v2.0.0-rc.76。

OpenAPI 2

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

[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

- saaj

我不理解为什么这个答案会被踩。它是唯一一个建议使用redoc-cli并且对我有效的答案。 - Jan Vlcinsky

现在有一个名为@redocly/cli的工具，我发现它比swagger-ui更易于使用和外观更好。 - Pier-Luc Gendreau

6

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

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

- Semaphor

5

静态文档在2.0版本中已经实现。可以到这里的./bin/static-docs.sh查看：

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

- fehguy

2

截至2018年4月，该GitHub链接中没有static-docs.sh，请修改。 - chrisinmtown

1

我确认没有这样的脚本。 - Marx

4

你可以使用：

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

- slal

3

我一直在使用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

- Shaun07776

2

如果你特别想要Swagger 2.0，我想指引你查看我的回答：将Swagger规范JSON转换为HTML文档，尽管我相信现在Swagger-Codegen已经支持Swagger 2.0了。

- Nils Knappmeier

0

生成文档实际上并不是必需的；你只需要一个OpenAPI/Swagger文件就可以了。

你可以简单地使用`swagger-ui-dist`来消费OpenAPI/Swagger文件，这个模块将Swagger-UI的整个`dist`文件夹作为一个无依赖的npm模块暴露出来。

示例：

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="description" content="SwaggerIU" />
    <title>SwaggerUI</title>
    <link rel="stylesheet" href="https://esm.sh/swagger-ui@4.19.0/dist/swagger-ui.css" />
</head>

<body>
    <div id="swagger-ui"></div>
    
    <script type="importmap">
        {
            "imports": {
                "swagger-ui-dist": "https://esm.sh/swagger-ui-dist@4.19.0/",
            }
        }
    </script>
    <script type="module" src="./main.js"></script>
</body>

</html>

将您的url: <...>添加到openapi文件中。

// main.js

// @ts-check
import swagger from "swagger-ui-dist"

const ui = swagger.SwaggerUIBundle({
    url: 'https://petstore3.swagger.io/api/v3/openapi.json',
    dom_id: '#swagger-ui',
})

要为swagger-ui-dist启用自动完成功能，您可以通过运行npm init -y来初始化npm，然后使用npm i -D @types/swagger-ui-dist进行安装。

- Filip Seman

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- ZigZagT · Accepted Answer

Use 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
修改~/templates中的.mustache模板以符合您的要求。
运行：swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location> -t <templates path>，其中<templates path>应为上面示例中的~/templates。