如何在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文档平台，并且可以选择性地聚合多个微服务的文档。

0 赞

0 踩