关于springboot:spring-boot-集成-swagger-30-指南

时隔 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 简略高效的轻代码开发框架