如何在Linux上通过Swagger进行API文档共享 - 问答

在Linux上通过Swagger进行API文档共享，可以按照以下步骤进行：

1. 安装Node.js和npm

首先，需要在Linux系统上安装Node.js和npm。可以通过以下命令进行安装：

# 更新包列表
sudo apt update
# 安装Node.js和npm
sudo apt install -y nodejs npm

2. 安装Swagger Editor和Swagger UI

安装Swagger Editor

# 下载Swagger Editor
wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.50.0.tar.gz
# 解压文件
tar -xvf swagger-editor-3.50.0.tar.gz
# 进入解压后的目录
cd swagger-editor-3.50.0
# 安装http-server全局
npm install -g http-server
# 启动Swagger Editor
http-server -p 8080

现在，可以通过浏览器访问 http://your_server_ip:8080 来使用Swagger Editor。

安装Swagger UI

# 下载Swagger UI
wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.50.0.tar.gz
# 解压文件
tar -xvf swagger-ui-3.50.0.tar.gz
# 进入解压后的目录
cd swagger-ui-3.50.0
# 安装express全局
npm install -g express
# 创建一个简单的HTML文件来加载Swagger Editor
mkdir public
cd public
nano index.html

在 index.html 文件中添加以下内容：

<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" type="text/css" href="swagger-editor.css">
</head>
<body>
<div id="swagger-editor"></div>
<script src="swagger-editor.js"></script>
<script>
window.onload = function() {
  // 原生 JavaScript 对 Swagger Editor 的支持
  // const url = "https://petstore.swagger.io/v2/swagger.json";
  // const url = "YOUR_SWAGGER_JSON_URL";
  // const editor = SwaggerEditor.create(url);
  // editor.load();
}
</script>
</body>
</html>

然后启动服务器：

cd ..
nohup node index.js &

访问 http://your_server_ip:3000 即可查看Swagger UI文档。

3. 编写OpenAPI规范文件

创建一个OpenAPI规范文件（YAML或JSON格式），详细定义API接口信息，包括路径、操作、参数、请求/响应格式等。以下是一个简单的YAML示例：

swagger: '2.0'
info:
  version: 1.0.0
  title: My API Documentation
  description: API文档示例
  contact:
    name: Your Name
    url: Your URL
  license:
    name: MIT
    url: http://opensource.org/licenses/MIT
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        200:
          description: 成功

4. 生成API文档

使用Swagger命令行工具生成API文档：

# 全局安装Swagger CLI
npm install -g swagger-jsdoc swagger-ui-express
# 生成Swagger文档
swagger generate spec -o ./swagger.json

启动Swagger服务：

swagger serve --no-open ./swagger.json

访问 http://your_server_ip:3000/swagger-ui.html 查看生成的API文档。

5. 集成Swagger到Spring Boot项目（可选）

如果使用Spring Boot项目，可以使用 springdoc 来生成API文档。首先，在 pom.xml 中添加依赖：

<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
springdoc.swagger-ui.path=/swagger-ui

启动Spring Boot应用后，访问 http://your_server_ip:8080/swagger-ui 即可查看生成的API文档。

6. 远程访问Swagger Editor（可选）

为了方便远程访问和团队协作，可以使用Docker进行部署。

# 拉取Swagger Editor容器
docker pull swaggerapi/swagger-editor
# 运行容器，将容器的8080端口映射到宿主机的8088端口
docker run -p 8088:8080 -d swaggerapi/swagger-editor

现在，可以通过浏览器访问 http://your_server_ip:8088 来使用Swagger Editor。

通过以上步骤，你可以在Linux上成功搭建Swagger环境，实现API文档的共享和管理。

0 赞

0 踩