swagger在ubuntu上的文档生成 - 问答

Ubuntu 上 Swagger OpenAPI 文档生成与发布

一准备环境

安装 Node.js 与 npm（用于本地运行 Swagger Editor/UI 或作为静态服务器）
- 命令：sudo apt update && sudo apt install -y nodejs npm
可选安装 Docker（用于容器化运行 UI 或生成器）
- 命令：sudo apt install -y docker.io
说明：Swagger 现已演进为 OpenAPI Specification（OAS），以下流程同时适用于 Swagger 2.0 与 OAS 3.x 的编写、展示与发布。

二方式一使用 Swagger Editor 编写与导出

本地运行 Editor（推荐）

下载发布包并启动：

wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.16.1.tar.gz
tar -xvf v3.16.1.tar.gz
cd swagger-editor-3.16.1
npm install
npm install -g http-server
http-server -p 8080

访问：http://localhost:8080，在编辑器中导入或编写 swagger.yaml/swagger.json，实时预览与校验。

仅用于展示时，也可直接运行官方容器：
```
docker pull swaggerapi/swagger-ui-express
docker run -p 8080:8080 swaggerapi/swagger-ui-express
```
访问 http://localhost:8080 使用 UI（默认加载示例规范，可通过环境变量或挂载自定义规范）。

三方式二在现有服务中集成 Swagger UI 展示文档

Node.js + Express 示例（静态托管或中间件托管）

安装依赖：npm i express swagger-ui-express yamljs

代码示例（保存为 index.js）：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const app = express();
const swaggerDocument = YAML.load('./swagger.yaml'); // 或 swagger.json
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server on ${PORT}`));

启动：node index.js，访问 http://localhost:3000/api-docs。

Docker 快速托管任意规范文件

docker run -p 8080:8080 \
  -e SWAGGER_JSON=/app/swagger.json \
  -v $(pwd):/app \
  swaggerapi/swagger-ui-express

将你的 swagger.json 放在当前目录即可在 http://localhost:8080 查看。

四方式三从代码注解自动生成 OpenAPI 规范

Go 项目（swaggo/swag）
- 安装：go install github.com/swaggo/swag/cmd/swag@latest
- 生成：swag init（生成 docs 目录）
- 在代码中添加注释后再次 swag init 更新文档。

Spring Boot 项目

使用 springdoc-openapi（推荐，适配新版本 Spring Boot）

依赖：

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.1.0</version>
</dependency>

访问：http://localhost:8080/docs

或使用 Springfox（旧方案）

依赖：

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

访问：http://localhost:8080/swagger-ui.html。

五规范校验与代码生成

校验与本地预览
- 使用 openapi-generator-cli 校验与启动本地预览服务：
```
docker run --rm -p 8080:8080 openapitools/openapi-generator-cli
```
  在容器内执行 validate 校验，或使用其预览能力进行快速检查。
代码生成（客户端/服务端存根）
- 示例（生成 Java 客户端）：
```
java -jar openapi-generator-cli-2.4.21.jar generate \
  -i ./path/to/swagger.yaml \
  -l java \
  -o ./output
```
可生成多语言客户端、服务器桩、API 文档等，便于前后端并行开发。

0 赞

0 踩