API文档自动化：SpringBoot + Swagger3接口文档生成的10个技巧

06-01 1653阅读

🌟博主介绍：Java、Python、js全栈开发 “多面手”，精通多种编程语言和技术，痴迷于人工智能领域。秉持着对技术的热爱与执着，持续探索创新，愿在此分享交流和学习，与大家共进步。

📖全栈开发环境搭建运行攻略：多语言一站式指南(环境搭建+运行+调试+发布+保姆级详解)

👉感兴趣的可以先收藏起来，希望帮助更多的人

API文档自动化：SpringBoot + Swagger3接口文档生成的10个技巧

API文档自动化：SpringBoot + Swagger3接口文档生成的10个技巧

一、Swagger3简介

1.1 什么是Swagger3

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger3 是 Swagger 的升级版，它基于 OpenAPI 3.0 规范，提供了更强大的功能和更好的兼容性。

1.2 为什么选择Swagger3

  • 可视化界面：Swagger3 提供了一个直观的 UI 界面，方便开发人员和测试人员查看和测试 API。
  • 自动生成文档：只需在代码中添加少量注解，Swagger3 就能自动生成详细的 API 文档。
  • 支持多种格式：可以生成 JSON、YAML 等格式的文档，方便与其他系统集成。

    二、SpringBoot集成Swagger3

    2.1 添加依赖

    在 pom.xml 中添加以下依赖：

        io.springfox
    springfox-boot-starter
    3.0.0

    2.2 配置Swagger3

    创建一个配置类，用于配置 Swagger3：

    import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
               .paths(PathSelectors.any())
               .build()
               .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
               .title("Spring Boot + Swagger3 API文档")
               .description("API文档详细描述")
               .version("1.0.0")
               .build();
    }
}

    2.3 访问Swagger UI

    启动 Spring Boot 应用程序，访问 http://localhost:8080/swagger-ui/index.html 即可看到 Swagger UI 界面。

    三、使用注解增强API文档

    3.1 @Api注解

    @Api 注解用于标记控制器类，提供控制器的基本信息：

    import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Tag(name = "用户管理", description = "用户管理相关接口")
public class UserController {
    // 控制器方法
}

    3.2 @ApiOperation注解

    @ApiOperation 注解用于标记控制器方法，提供方法的基本信息：

    import io.swagger.v3.oas.annotations.Operation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserController {
    @GetMapping("/users")
    @Operation(summary = "获取所有用户", description = "获取系统中所有用户的信息")
    public String getUsers() {
        return "All users";
    }
}

    3.3 @ApiParam注解

    @ApiParam 注解用于标记方法参数，提供参数的详细信息：

    import io.swagger.v3.oas.annotations.Parameter;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserController {
    @GetMapping("/user")
    public String getUser(@Parameter(name = "id", description = "用户ID", required = true) @RequestParam Long id) {
        return "User with id: " + id;
    }
}

    四、分组管理API文档

    4.1 配置多个Docket

    可以通过配置多个 Docket 实例来实现 API 文档的分组管理：

    import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket userApi() {
        return new Docket(DocumentationType.OAS_30)
               .groupName("用户管理")
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller.user"))
               .paths(PathSelectors.any())
               .build()
               .apiInfo(apiInfo());
    }
    @Bean
    public Docket orderApi() {
        return new Docket(DocumentationType.OAS_30)
               .groupName("订单管理")
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller.order"))
               .paths(PathSelectors.any())
               .build()
               .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
               .title("Spring Boot + Swagger3 API文档")
               .description("API文档详细描述")
               .version("1.0.0")
               .build();
    }
}

    4.2 访问分组文档

    在 Swagger UI 界面中，可以通过下拉菜单选择不同的分组查看相应的 API 文档。

    五、隐藏不必要的API

    5.1 使用PathSelectors

    可以通过 PathSelectors 来过滤不需要显示的 API：

    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.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
               .paths(PathSelectors.ant("/api/**"))
               .build();
    }
}

    上述代码只显示以 /api/ 开头的 API。

    5.2 使用@ApiIgnore注解

    在控制器类或方法上添加 @ApiIgnore 注解，可以忽略该类或方法的 API 文档：

    import io.swagger.v3.oas.annotations.Hidden;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserController {
    @GetMapping("/users")
    public String getUsers() {
        return "All users";
    }
    @GetMapping("/internal")
    @Hidden
    public String internalApi() {
        return "Internal API";
    }
}

    六、自定义响应消息

    6.1 使用@ApiResponse注解

    @ApiResponse 注解用于定义 API 方法的响应消息：

    import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserController {
    @GetMapping("/user")
    @Operation(summary = "获取用户信息")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "成功获取用户信息"),
            @ApiResponse(responseCode = "404", description = "用户不存在")
    })
    public String getUser() {
        return "User info";
    }
}

    6.2 全局响应消息配置

    可以通过实现 WebMvcConfigurer 接口来配置全局的响应消息：

    import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class WebConfig implements WebMvcConfigurer {
    // 配置全局响应消息
}

    七、处理复杂数据类型

    7.1 自定义模型转换器

    当遇到复杂数据类型时，可以自定义模型转换器来处理：

    import com.fasterxml.jackson.databind.module.SimpleModule;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.spring.web.json.JacksonModuleRegistrar;
@Configuration
public class SwaggerModelConfig {
    @Bean
    public JacksonModuleRegistrar swaggerJacksonModuleRegistrar() {
        return objectMapper -> {
            SimpleModule module = new SimpleModule();
            // 注册自定义序列化器和反序列化器
            objectMapper.registerModule(module);
        };
    }
}

    7.2 使用@Schema注解

    @Schema 注解用于描述模型类的属性：

    import io.swagger.v3.oas.annotations.media.Schema;
@Schema(description = "用户信息")
public class User {
    @Schema(description = "用户ID", example = "1")
    private Long id;
    @Schema(description = "用户名", example = "John Doe")
    private String name;
    //  getter 和 setter 方法
}

    八、集成Swagger3到生产环境

    8.1 条件配置

    可以通过条件配置来控制 Swagger3 在生产环境中是否启用：

    import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    @Profile("!prod")
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
               .paths(PathSelectors.any())
               .build();
    }
}

    上述代码表示只有在非生产环境中才启用 Swagger3。

    8.2 安全访问

    在生产环境中，可以通过配置安全访问来限制 Swagger UI 的访问：

    import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;
@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
               .authorizeRequests()
               .antMatchers("/swagger-ui/**", "/v3/api-docs/**").authenticated()
               .anyRequest().permitAll()
               .and()
               .httpBasic();
        return http.build();
    }
}

    九、自动化测试与Swagger3

    9.1 生成测试用例

    可以根据 Swagger3 生成的 API 文档自动生成测试用例，例如使用 Postman 等工具导入 Swagger 文档并生成测试用例。

    9.2 持续集成

    将 Swagger3 集成到持续集成流程中，每次代码更新后自动生成 API 文档并进行测试，确保 API 的稳定性。

    十、性能优化与缓存

    10.1 缓存 Swagger 文档

    可以使用缓存技术来缓存 Swagger 生成的 API 文档，减少每次请求时的生成时间：

    import org.springframework.cache.annotation.Cacheable;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
               .paths(PathSelectors.any())
               .build();
    }
    @Cacheable("swagger-docs")
    public Object getSwaggerDocs() {
        // 获取 Swagger 文档
        return null;
    }
}

    10.2 优化 Swagger 扫描

    减少不必要的包扫描范围，只扫描需要生成 API 文档的控制器类，提高性能。

免责声明：我们致力于保护作者版权，注重分享，被刊用文章因无法核实真实出处，未能及时与作者取得联系，或有版权异议的，请联系管理员，我们会立即处理! 部分文章是来自自研大数据AI进行生成,内容摘自(百度百科,百度知道,头条百科,中国民法典,刑法,牛津词典,新华词典,汉语词典,国家院校,科普平台)等数据,内容仅供学习参考,不准确地方联系删除处理! 图片声明：本站部分配图来自人工智能系统AI生成,觅知网授权图片,PxHere摄影无版权图库和百度，360，搜狗等多加搜索引擎自动关键词搜索配图，如有侵权的图片，请第一时间联系我们。

相关阅读

目录[+]

取消
微信二维码
微信二维码
支付宝二维码