Ubuntu下Swagger集成有哪些步驟

Ubuntu下Swagger集成的常見步驟（以Node.js/Express和Spring Boot為例）

一、通用前置準備

在Ubuntu上集成Swagger前，需確保系統具備Node.js/npm（用于前端工具鏈）和Java（部分Java項目依賴）環境：

1. 安裝Node.js和npm（適用于Node.js/Express項目）：

   sudo apt update
   sudo apt install -y nodejs npm
   

   驗證安裝：node -v（顯示版本號）、npm -v（顯示版本號）。

2. 安裝Java（適用于Spring Boot項目）：

   sudo apt update
   sudo apt install -y openjdk-11-jdk
   

   驗證安裝：java -version（顯示Java版本信息）。

二、Node.js/Express項目集成Swagger

若項目基于Node.js+Express框架，可通過swagger-jsdoc（生成文檔）和swagger-ui-express（集成UI）快速實現：

1. 安裝Swagger工具（全局或項目本地）：

   sudo npm install -g swagger-jsdoc swagger-ui-express  # 全局安裝（可選）
   cd your-project-directory
   npm install --save swagger-jsdoc swagger-ui-express  # 項目本地安裝（推薦）
   

2. 創建Swagger配置文件：
   在項目根目錄新建swagger.yaml（或swagger.json），定義API基本信息、路徑、模型等。示例如下：

   swagger: '2.0'
   info:
     title: Sample API
     description: A demo API for Swagger integration
     version: '1.0.0'
   host: localhost:3000
   basePath: /api
   schemes:
     - http
   paths:
     /users:
       get:
         summary: Get all users
         responses:
           '200':
             description: A list of users
             schema:
               type: array
               items:
                 $ref: '#/definitions/User'
   definitions:
     User:
       type: object
       properties:
         id:
           type: integer
           format: int64
         name:
           type: string
   

3. 集成Swagger UI到Express應用：
   修改Express主文件（如app.js），添加以下代碼：

   const express = require('express');
   const swaggerUi = require('swagger-ui-express');
   const swaggerDocument = require('./swagger.yaml'); // 引入配置文件
   
   const app = express();
   app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); // 掛載Swagger UI
   
   // 其他路由（如用戶接口）
   app.get('/api/users', (req, res) => {
     res.json([{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]);
   });
   
   const PORT = process.env.PORT || 3000;
   app.listen(PORT, () => console.log(`Server running on port ${PORT}`));
   

4. 運行并訪問Swagger UI：

   node app.js
   

   打開瀏覽器訪問http://localhost:3000/api-docs，即可看到Swagger UI界面，包含API文檔和測試功能。

三、Spring Boot項目集成Swagger

若項目基于Spring Boot框架，可通過Springfox Swagger依賴自動生成文檔：

1. 添加Swagger依賴：
   在pom.xml（Maven）中添加以下依賴：

   <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>
   

2. 配置Swagger：
   創建配置類（如SwaggerConfig.java），啟用Swagger并定義掃描范圍：

   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import springfox.documentation.builders.PathSelectors;
   import springfox.documentation.builders.RequestHandlerSelectors;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
       @Bean
       public Docket api() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) // 替換為你的控制器包路徑
                   .paths(PathSelectors.any())
                   .build();
       }
   }
   

3. 運行并訪問Swagger UI：
   使用Maven啟動Spring Boot應用：

   ./mvnw spring-boot:run
   

   打開瀏覽器訪問http://localhost:8080/swagger-ui.html，即可查看自動生成的API文檔。

四、可選：Docker集成Swagger UI

若不想手動安裝，可使用Docker快速部署Swagger UI：

1. 安裝Docker：

   sudo apt update
   sudo apt install -y docker.io
   sudo systemctl start docker
   sudo systemctl enable docker
   

2. 運行Swagger UI容器：

   docker pull swaggerapi/swagger-ui
   docker run -d -p 8080:8080 --name swagger-ui swaggerapi/swagger-ui
   

   訪問http://localhost:8080，通過界面輸入Swagger規范文件URL（如http://your-server-ip:3000/api-docs）即可查看文檔。

以上步驟覆蓋了Ubuntu下Swagger集成的常見場景，可根據項目技術棧選擇對應方案。集成后，可通過Swagger UI直觀查看API文檔、測試接口，提升開發效率。