springboot集成springdoc-openapi-ui

• swagger 2.X是springboot用于生成在线文档的工具，基于OpenApi2
• springdoc-openapi-ui 则是基于OpenApi3，可以看成是swagger3，因为导入之后一些注解的包名都是 io.swagger.v3.oas.annotations
• baidu出来的都被swagger 2占领了，基本搜不到文档，想要查阅请自行谷歌
• 文档上说springdoc-openapi-ui能够在webflux的项目中使用，尚未尝试，留几个文档地址请自行查阅
• https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations
• https://github.com/springdoc-openapi
• https://springdoc.github.io/springdoc-openapi-demos/

依赖

    implementation 'org.springdoc:springdoc-openapi-ui:1.2.3'

使用

• springdoc-openapi-ui作为springboot的组件，几乎全部使用注解进行配置，与swagger2不同的是较好依赖之后不用写任何配置文件，直接生效
• 在线文档访问页面地址为(/v3/api-docs地址是组件生成的json的地址)：

http://host:port/swagger-ui/index.html?url=/v3/api-docs

• 可在配置文件中开启或者关闭：

springdoc:
  api-docs:
    enabled: true

注解说明

@OpenAPIDefinition(
        info = @Info(
                title = "标题",
                version = "1.0",
                description = "描述信息"
        ),
        externalDocs = @ExternalDocumentation(description = "参考文档",
                url = "https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations"
        )
)

• @OpenAPIDefinition在springboot之中只会生效一个，用于描述该服务的全局信息

@RestController
@Tag(name = "HelloController")
public class HelloController {

    @GetMapping("/hello2")
    public String hello2() {
        return "hello world v3";
    }

}

• @Tag可以加在类和方法上，swagger2中controller会自动加上，用来在页面中显示某个接口属于某个controller，在这里需要手动加上

@Operation(summary = "测试登录的接口",
            description = "描述的文字",
            responses = {
                    @ApiResponse(description = "登录信息",
                            content = @Content(mediaType = "application/json",
                                    schema = @Schema(implementation = UserModel.class))),
                    @ApiResponse(responseCode = "400", description = "返回400时候错误的原因")},
            security = @SecurityRequirement(name = "需要认证"))
    @GetMapping("/login")
    public UserModel login(
            @Parameter(description = "用户名")
            @RequestParam(value = "username", required = false) String username,
            @Parameter(description = "密码")
            @RequestParam(value = "password") String password) {
        UserModel userModel = new UserModel();
        userModel.setUsername(username);
        userModel.setPassword(password);
        return userModel;
    }

• 接口的注解@Operation，主要用来描述一些接口的信息
• @Parameter用来描述一些传入参数的信息，但是我个人不建议使用这种方式

 @Operation(summary = "swagger v3 信息全部写头上", description = "描述的文字",
            parameters = {
                    @Parameter(name = "auth", description = "请求头", in = ParameterIn.HEADER),
                    @Parameter(name = "id", description = "id", in = ParameterIn.PATH),
                    @Parameter(name = "param", description = "参数"),
            },
            responses = {@ApiResponse(responseCode = "400", description = "400错误")},
            security = @SecurityRequirement(name = "需要认证"))
    @GetMapping("/param/{id}")
    public String param(HttpServletRequest httpServletRequest,
                        @RequestParam(value = "param") String param,
                        @PathVariable(value = "id") String id) {
        String auth = httpServletRequest.getHeader("auth");
        return "查看参数： " + auth;
    }

• 这种方式则是把参数都放在了 @Operation之中，in可以指定参数来源

@Data
@Schema(name="UserModel", description="用户model")
public class UserModel {

    @Schema(description = "用户名")
    private String username;
    @Schema(description="密码")
    private String password;

}

• @Schema可以注解实体类，swagger页面上显示实体类的信息

• 没有中文文档，只能先解读一些常用的，后续有发现了再更新
• 本项目git地址：https://github.com/ladyishenlong/infinite-project