如何利用Swagger在Linux上進行API文檔的持續集成

以下是在Linux上利用Swagger實現API文檔持續集成的步驟：

1. 安裝基礎環境
   • 安裝Java（11+）和構建工具（Maven/Gradle）：

     sudo apt update && sudo apt install openjdk-11-jdk maven
     

2. 添加Swagger依賴
   • Maven項目在pom.xml中添加：

     <dependency>
         <groupId>org.springdoc</groupId>
         <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
         <version>2.6.0</version> <!-- 以最新版為準 -->
     </dependency>
     

3. 配置Swagger
   • 創建配置類（Spring Boot示例）：

     @Configuration
     public class SwaggerConfig {
         @Bean
         public OpenAPI customOpenAPI() {
             return new OpenAPI()
                 .info(new Info().title("API文檔").version("1.0"));
         }
     }
     

4. 集成到CI/CD工具
   • Jenkins：在Jenkinsfile中添加文檔生成步驟：

     stage('Generate Swagger Docs') {
         steps {
             sh 'mvn springdoc:generate'
         }
         post {
             archiveArtifacts artifacts: 'target/generated-docs/**'
         }
     }
     

   • GitLab CI/CD：在.gitlab-ci.yml中配置：

     stages:
       - document
     generate_docs:
       stage: document
       script:
         - mvn springdoc:generate
       artifacts:
         paths:
           - target/generated-docs
     

5. 自動化測試與部署
   • 集成測試工具（如JUnit）驗證API功能，通過CI/CD管道自動部署文檔到Web服務器（如Nginx）。

說明：Spring Boot 3.x推薦使用springdoc-openapi替代舊版springfox，支持OpenAPI 3.0規范，生成文檔更簡潔。