spring boot 集成 swagger 3.0 指南

时隔2年，swagger终于在社区推动下迎来了2.9版本之后的大版本升级：v3.0
swagger 3.0 release notes

3.0版本在配置上与2.9稍有差别，包括依赖包改为: springfox-boot-starter，启用注解更改为: @EnableOpenApi等。

具体使用步骤：

1. 引入依赖springfox-boot-starter：

以maven为例：

<!-- 引入Swagger3依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2. 自定义配置信息

/**
* Swagger配置类
*/
@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket docket(){
       return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo()).enable(true)
                .select()
                //apis： 添加swagger接口提取范围
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("XX项目接口文档")
                .description("XX项目描述")
                .contact(new Contact("作者", "作者URL", "作者Email"))
                .version("1.0")
                .build();
    }
}

3. 在你的Controller上添加swagger注解

以下为依赖diboot-core为例：

@Api(tags="用户管理")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation("用户列表")
    @GetMapping("/{id}")
    public JsonResult getViewObjectMapping(@PathVariable("id") Long id) throws Exception{
        return super.getViewObject(id, UserVO.class);
    }
    ...
}

4. 如启用了访问权限，还需将swagger相关uri允许匿名访问

具体需要添加的uri有：

/swagger**/**
/webjars/**
/v3/**
/doc.html

5. 启动应用，访问/swagger-ui/index.html

---

diboot 简单高效的低代码开发框架