Spring Boot Swagger2配置与应用指南

初始化Spring Boot项目环境

创建一个新的Spring Boot项目，确保项目依赖中包含必要的组件。重点添加以下依赖：


       
    
     io.springfox
        
    
     springfox-swagger2
        
    
     2.9.2
    
   
       
    
     io.springfox
        
    
     springfox-swagger-ui
        
    
     2.9.2
    
   
       
    
     org.springframework.boot
        
    
     spring-boot-starter-web
        
    
     2.5.0

Swagger2配置示例

通过以下配置类实现Swagger2的集成：

@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .pathMapping("/")                .select()                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))                .paths(PathSelectors.any())                .build()                .apiInfo(new ApiInfoBuilder()                        .title("Spring Boot Swagger文档")                        .description("详细的API文档说明")                        .version("1.0.0")                        .contact(new Contact("Swagger团队", "http://example.com", "support@example.com"))                        .license("Apache License 2.0")                        .licenseUrl("http://www.apache.org"));    }}

接口注解使用指南

在实际开发中，注解的使用非常重要：

@Api：标记一个Controller类，说明它的功能。

@ApiOperation：描述一个方法的作用，提供API的详细说明。

@ApiImplicitParams：定义参数，支持默认值和必填属性。

@ApiModel：用于实体类注释，描述字段的作用和约束条件。

示例代码：

@RestController@Api(tags = "用户管理接口")@RequestMapping("/user")public class UserController {    @PostMapping("/")    @ApiOperation("添加用户")    @ApiImplicitParams({            @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "李四"),            @ApiImplicitParam(name = "address", value = "地址", defaultValue = "深圳", required = true)    })    public RespBean addUser(@RequestBody User user) {        // 实现用户添加逻辑        return new RespBean("200", "用户添加成功");    }        @GetMapping("/{id}")    @ApiOperation("查询用户信息")    @ApiImplicitParam(name = "id", value = "用户ID", defaultValue = "1", required = true)    public User getUserById(@PathVariable Long id) {        // 实现用户查询逻辑        User user = new User();        user.setId(id);        return user;    }}

安全配置注意事项

在Spring Security中，为了确保Swagger2文档的访问：

@Overrideprotected void configure(WebSecurity web) throws Exception {    web.ignoring()        .antMatchers("/swagger-ui.html")        .antMatchers("/v2/**")        .antMatchers("/swagger-resources/**");}

这样配置后， Swagger页面和文档将不受认证限制，确保开发和测试环境的顺利运行。

常见问题解答

为什么 Swagger文档被403Forbidden了？

检查Security配置，确保Swagger相关路径未被拦截。

可以在安全配置中添加忽略路径，例如：

web.ignoring()    .antMatchers("/swagger-ui.html")    .antMatchers("/v2/**")    .antMatchers("/swagger-resources/**");

如何处理参数默认值？

使用@ApiImplicitParam注解，指定defaultValue属性即可：

@ApiImplicitParam(name = "username", value = "李四", defaultValue = "李四")

如何展示请求示例？

在@ApiOperation中使用example字段：

@ApiOperation(example = "2020-01-01", requestMethod = "GET")

通过以上配置和示例，可以轻松完成Spring Boot项目的Swagger2集成与文档编写，提升开发效率和API文档的可读性。

转载地址：http://adwwz.baihongyu.com/

你可能感兴趣的文章