pom文件

修改pom文件,引入相应jar文件.

<dependency>
			<groupId>org.springdoc</groupId>
			<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
			<version>2.0.2</version>
		</dependency>

openapi的配置文件

@Configuration
public class OpenapiConfiguration {

    @Bean
    public OpenAPI restfulOpenAPI() {
        Info info = new Info().title("Spring boot demo api project")
                .description("openapi-demo")
                .version("1.0.0")
                .license(new License().name("Apache 2.0").url("http://springdoc.org"));
        return new OpenAPI()
                .info(info)
                .externalDocs(new ExternalDocumentation()
                        .description("SpringDoc Wiki Documentation")
                        .url("https://springdoc.org/v3"));
    }
}

Web 控制器编写

@Tag(name = "演示组")
@RestController
@RequestMapping("/demo")
public class SwaggerDemoController {

    @Operation(method = "POST", summary = "RequestParam参数请求方式")
    @PostMapping(value = "/post-query", produces = {"application/json"})
    public ListResponse<City> getSchool(@Parameter(name = "schoolId", description = "学校ID", required = true, example = "88")
                                                          @RequestParam Integer schoolId,
                                                          @Parameter(name = "schoolName", description = "学校名称", required = false, example = "xx中心")
                                                          @RequestParam String schoolName) {
        return new ListResponse<City>(Collections.emptyList());
    }

访问项目的swagger-ui的地址, 比如 http://localhost:9090/swagger-ui/index.html

兼容 Swagger 2.0

springdoc使用OpenAPI 3.0 规范来生成 API 文档的方式。虽然它不是直接兼容 Swagger 2.0，但是可以通过配置将 OpenAPI 3.0 规范转换为 Swagger 2.0 规范。 在项目的配置文件中增加如下配置即可.

springdoc:
  api-docs:
    enabled: true
    path: /v2/api-docs

springfox迁移到springdoc

springdoc中的产生文档注解使用时跟springfox不一致,对照关系如下

@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")