Ubuntu环境下Swagger的常见使用案例
适用于需要自定义API文档界面的开发场景,通过Express整合Swagger UI,实现本地API文档的可视化与测试。
sudo apt update && sudo apt install nodejs npm
)。sudo npm install -g swagger-ui-express yamljs
)。app.js
文件,加载Swagger文档(如swagger.yaml
)并通过/api-docs
端点提供访问:const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const app = express();
const swaggerDocument = YAML.load('./swagger.yaml'); // 加载Swagger定义
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
app.listen(3000, () => console.log('Server running on port 3000'));
swagger.yaml
文件,定义API基本信息(标题、版本)、主机地址、路径及响应格式(如/users
接口的GET请求返回用户列表)。node app.js
启动服务,浏览器访问http://localhost:3000/api-docs
即可查看交互式API文档。适用于希望避免环境配置复杂度的场景,通过Docker容器快速启动Swagger UI服务。
sudo apt update && sudo apt install docker.io
安装Docker。docker pull swaggerapi/swagger-ui
)。/path/to/swagger.json
)挂载至容器,并映射端口(docker run -p 80:8080 -v /path/to/swagger.json:/usr/src/app/swagger.json swaggerapi/swagger-ui
)。http://localhost
即可查看Swagger UI界面,直接加载挂载的Swagger文档。适用于Java Spring Boot开发者,通过注解自动生成Swagger文档,实现代码与文档同步。
pom.xml
中引入Springfox Swagger2和Swagger UI依赖(如springfox-boot-starter
)。SwaggerConfig.java
),指定API分组、扫描路径及文档信息(标题、描述、版本)。@Api
、@ApiOperation
、@ApiResponse
)标注接口信息。./mvnw spring-boot:run
),浏览器访问http://localhost:8080/swagger-ui.html
即可查看自动生成的API文档。适用于API设计阶段,通过Swagger Editor可视化编写Swagger文档并实时测试接口。
sudo npm install -g swagger-editor
)或下载源码解压。swagger-editor
命令,浏览器自动打开http://localhost:8080
。