如何在Linux上搭建Swagger API文檔平臺

在Linux上搭建Swagger API文檔平臺可以通過以下步驟實現：

1. 安裝必要的軟件和依賴

首先，確保你的Linux系統上已經安裝了Java開發環境（JDK）和Maven。如果沒有安裝，可以使用以下命令進行安裝：

# 安裝JDK
sudo apt update
sudo apt install openjdk-11-jdk

# 驗證JDK安裝
java -version

# 安裝Maven
sudo apt install maven

# 驗證Maven安裝
mvn -version

2. 創建Spring Boot項目

使用Spring Initializr創建一個新的Spring Boot項目，選擇以下依賴：

• Spring Web
• Swagger Starter

3. 配置Swagger

在你的Spring Boot項目中，創建一個配置類來啟用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"))
                .paths(PathSelectors.any())
                .build();
    }
}

4. 添加Swagger UI依賴

在你的pom.xml文件中添加Swagger UI的依賴：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

5. 啟動Spring Boot應用

使用以下命令啟動你的Spring Boot應用：

mvn spring-boot:run

6. 訪問Swagger UI

啟動應用后，打開瀏覽器并訪問以下URL來查看Swagger UI：

http://localhost:8080/swagger-ui.html

7. 聚合多個服務的Swagger文檔（可選）

如果你有多個微服務，并且希望在一個統一的界面中查看所有服務的Swagger文檔，可以使用Spring Cloud Gateway來聚合這些文檔。以下是一個簡單的示例：

7.1 創建一個網關項目

使用Spring Initializr創建一個新的Spring Cloud Gateway項目，并添加以下依賴：

• Spring Web
• Spring Cloud Gateway
• Eureka（如果你使用服務發現）

7.2 配置網關

在你的網關項目中，創建一個配置類來聚合Swagger文檔：

import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cloud.gateway.route.builder.RouteLocatorBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class GatewayConfig {
    @Bean
    public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
        return builder.routes()
                .route("order-service", r -> r.path("/order/**")
                        .uri("lb://order-service"))
                .route("stock-service", r -> r.path("/stock/**")
                        .uri("lb://stock-service"))
                .build();
    }
}

7.3 配置每個微服務的Swagger

在每個微服務中，配置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.order.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

7.4 訪問聚合的Swagger文檔

在網關的Swagger UI中，你可以看到所有微服務的文檔接口，并通過網關訪問這些接口。

通過以上步驟，你就可以在Linux上成功搭建一個Swagger API文檔平臺，并且可以選擇性地聚合多個微服務的文檔。