1. 准备Linux环境基础依赖
在Linux系统上,首先需要安装Node.js和npm(Node.js包管理器),这是Swagger Editor和Swagger UI运行的基础环境。以Ubuntu/Debian为例,可通过以下命令安装:
curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash - # 添加Node.js源
sudo apt-get install -y nodejs # 安装Node.js及npm
安装完成后,通过node -v
和npm -v
验证安装是否成功。
2. 安装并启动Swagger Editor(可选,用于编写/编辑API定义)
Swagger Editor是在线编写和验证OpenAPI规范的工具,支持实时语法检查和预览。
sudo npm install -g swagger-editor # 全局安装Swagger Editor
swagger-editor # 启动本地服务(默认端口8080)
docker pull swaggerapi/swagger-editor:v4.6.0 # 拉取最新版镜像
docker run -d -p 8080:8080 --name swagger-editor swaggerapi/swagger-editor:v4.6.0 # 运行容器
启动后,通过浏览器访问http://<服务器IP>:8080
即可使用Swagger Editor。3. 安装并启动Swagger UI(用于可视化展示API文档)
Swagger UI是将OpenAPI规范(YAML/JSON)渲染为交互式文档的工具,支持“Try it out”等功能。
sudo npm install -g swagger-ui-express express # 安装依赖
mkdir swagger-ui-project && cd swagger-ui-project # 创建项目目录
创建index.js
文件,配置静态文件服务和Swagger UI:const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json'); // 引入OpenAPI定义文件
const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); // 映射访问路径
app.listen(3000, () => console.log('Swagger UI运行在 http://localhost:3000/api-docs'));
启动服务:node index.js
。docker pull swaggerapi/swagger-ui:v4.15.5 # 拉取镜像
docker run -d -p 8081:8080 --name swagger-ui -e SWAGGER_FILE=/app/swagger.yaml -v /path/to/swagger.yaml:/app/swagger.yaml swaggerapi/swagger-ui:v4.15.5 # 挂载定义文件
访问http://<服务器IP>:8081
即可查看文档。4. 编写OpenAPI规范文件(核心:定义API结构)
OpenAPI规范(YAML或JSON格式)是Swagger文档的基础,需描述API的路径、操作、参数、响应、模型等信息。示例如下(swagger.yaml
):
swagger: '2.0'
info:
title: Linux API文档示例
version: 1.0.0
description: 用于演示Linux环境下的API文档共享
basePath: /api/v1
schemes:
- http
paths:
/users:
get:
summary: 获取用户列表
description: 返回所有用户的ID和名称
responses:
'200':
description: 成功获取用户列表
schema:
type: array
items:
$ref: '#/definitions/User'
definitions:
User:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 张三
将上述文件保存为swagger.yaml
(或swagger.json
),放置在项目根目录或指定路径。
5. 集成Swagger到应用(可选,自动生成文档)
若使用Spring Boot框架,可通过springdoc-openapi
依赖自动生成OpenAPI规范,无需手动编写:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.1.0</version>
</dependency>
application.properties
):springdoc.api-docs.path=/api-docs # OpenAPI规范路径
springdoc.swagger-ui.path=/swagger-ui # Swagger UI访问路径
http://<服务器IP>:8080/swagger-ui
即可查看自动生成的文档。6. 共享API文档的方法
http://<公网IP>:8080
(Swagger Editor)或http://<公网IP>:8081/api-docs
(Swagger UI)访问。curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash # 安装Cpolar
sudo systemctl start cpolar # 启动服务
cpolar http 8080 # 映射Swagger Editor的8080端口
根据Cpolar返回的公网地址(如https://xxx.cpalr.com
)访问文档。server {
listen 80;
server_name your-domain.com;
location /api-docs {
auth_basic "Restricted Access";
auth_basic_user_file /etc/nginx/.htpasswd; # 存放用户名密码的文件
proxy_pass http://localhost:3000; # 代理到Swagger UI服务
}
}
通过htpasswd
命令创建密码文件:htpasswd -c /etc/nginx/.htpasswd admin
。通过以上步骤,即可在Linux环境下完成Swagger的部署与配置,实现API文档的共享与协作。