接口文档管理系列 Springboot集成springdoc

springdoc-openapi 带有Spring-boot的OpenAPI 3库

springdoc-openapi Java库有助于使用Spring
Boot项目自动生成API文档。springdoc-openapi的工作原理是在运行时检查应用程序，以基于spring配置，类结构和各种注释来推断API语义。
自动生成JSON / YAML和HTML格式的API文档。可以使用swagger-api注释通过注释来完成本文档。

该库支持：

OpenAPI 3
springboot（v1和v2）
JSR-303，专门用于@ NotNull，@ Min，@ Max和@Size。
Swagger-ui OAuth 2

springdoc 官网地址

springdoc架构图

如何使用？

引入依赖

build.gradle

    compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
    compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
    
    compile group: 'org.springdoc', name: 'springdoc-openapi-core', version: '1.1.49'
    compile group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.4.3'
    
    compile group: 'org.springdoc', name: 'springdoc-openapi-gradle-plugin', version: '1.3.0'
    
    compile group: 'com.github.xiaoymin', name: 'knife4j-spring-boot-starter', version: '2.0.4'

码代码

swagger和knife4j配置类

/**
 * 为了使用swagger-ui和knife4j
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfiguration {
  /*  @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//这是注意的代码 在Action上加注解@Api
//                .apis(RequestHandlerSelectors.basePackage("com.anoo.Controller"))//这是注意的代码 扫描包方式
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Pet接口文档")
                .description("Pet相关接口的文档")
                .termsOfServiceUrl("https://blog.csdn.net/wangxudongx")
                .version("1.0")
                .contact("[email protected]")
                .license("asdfsdafsdf poewr by xxx")
                .build();
    }*/
}

定义model

@Schema(title = "店铺model")
public class Store implements Serializable {

    /**
     * `@Schema`在使用到字段上面时name属性一定要跟字段名一致
     */
    @Schema(description = "店铺编号" , name = "id",title = "店铺ID" , minimum = "1",maximum = "10000")
    private Integer id;

    @Schema(description = "店铺名称",name = "name",title = "店铺Name" , maxLength = 5)
    private String name;
    @Override
    public String toString() {
        return "Store{" +
                "id=" + id +
                ", name='" + name + '\'' +
                '}';
    }

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

}

Controller

必须使用@RestController注解springdoc才识别

@Schema在使用到字段上面时name属性一定要跟字段名一致

@RequestMapping("/store")
@RestController
public class StoreController {

    @Operation(description = "store / get")
    @GetMapping("get/{id}")
    public ResponseEntity get(@PathVariable Integer id) {
        return new ResponseEntity("success", HttpStatus.OK);
    }

    @Operation(summary = "新增一个店铺",description = "post 新增一个店铺")
    @PostMapping("add")
    public ResponseEntity add(
            @RequestBody Store store) {

        return new ResponseEntity(store.toString() , HttpStatus.OK);
    }


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

        Store store = new Store();

        return new ResponseEntity(store,HttpStatus.OK);
    }
}

knife4j

knife4j正常使用

---

---

导读

接口文档管理系列 OpenAPI规范及Swagger工具集

接口文档管理系列 Spring MVC框架整合Swagger