都说好记性不如烂笔头,每天写一点,从量变到质变的开始!废话不多说,以下所有内容均来自本人实际操作:

1.为什么使用Swagger3(OpenAPI3)?

• swagger官方文档介绍的功能太过复杂,作为一个后端开发,我们往往只需要用它来自动生成接口文档,而Swagger2早就不维护了,因此通过这篇博客找到了springdoc官网
• springdoc-openapi Java库有助于使用Spring Boot项目自动生成API文档.springdoc-openapi的工作原理是在运行时检查应用程序,以基于spring配置,类结构和各种注释来推断API语义,自动生成JSON / YAML和HTML格式的API文档,可以使用swagger-api注释通过注释来完成本文档.

2.新建Spring Boot项目,添加OpenAPI依赖(不需要其他配置)

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.2</version>
</dependency>

3.启动项目访问试试(http://localhost:8080/swagger-ui.html)

4. 修改yml配置文件,自定义swagger配置

4.1 自定义swagger访问html首页

springdoc:
  swagger-ui:
    path: /swagger/index.html

4.2 禁用springdoc-openapi

springdoc:
  api-docs:
    enabled: false

4.3 禁用swagger-ui

springdoc:
  swagger-ui:
    enabled: false

 4.4 除了来自swagger-annotations的@Hidden注释之外,还可以使用程序包或路径配置来限制生成的OpenAPI描述

# Packages to include
springdoc.packagesToScan=com.package1, com.package2
# Paths to include
springdoc.pathsToMatch=/v1, /api/balance/**

4.5 springdoc-openapi核心属性

4.6  swagger-ui属性

5.从SpringFox迁移

5.1 删除springfox和swagger 2依赖项,添加springdoc-openapi-ui

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.5.2</version>
   </dependency>

5.2 将swagger 2注释替换为swagger 3注释(它已经包含在springdoc-openapi-ui依赖项中) 

• @Api → @Tag 用于类,标识这个类是swagger的资源

• @ApiIgnore→@Parameter(hidden = true)或@Operation(hidden = true)或@Hidden 用于类,方法,方法参数,表示这个方法或者类被忽略

• @ApiImplicitParam → @Parameter 用于方法,表示单独的请求参数

• @ApiImplicitParams → @Parameters 用于方法,包含多个请求参数

• @ApiModel → @Schema 用于类 ,表示对类进行说明，用于参数用实体类接收

• @ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY) 参数实体类某个参数不显示到接口文档中

• @ApiModelProperty → @Schema 用于方法,字段,表示对model属性的说明或者数据操作更改

• @ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar") 用于方法,表示一个http请求的操作​​​​​​​

• @ApiParam → @Parameter 用于方法,参数,字段说明,表示对参数的添加元数据(说明或是否必填等)​​​​​​​

• @ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo") 用在@ApiResponses中，一般用于表达一个错误的响应信息​​​​​​​

5.3 此步骤是可选的：仅当您有多个 Docketbean时，才用bean替换它们(GroupedOpenApi)

之前:

@Bean
  public Docket publicApi() {
      return new Docket(DocumentationType.SWAGGER_2)
              .select()
              .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
              .paths(PathSelectors.regex("/public.*"))
              .build()
              .groupName("springshop-public")
              .apiInfo(apiInfo());
  }

  @Bean
  public Docket adminApi() {
      return new Docket(DocumentationType.SWAGGER_2)
              .select()
              .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin"))
              .paths(PathSelectors.regex("/admin.*"))
              .build()
              .groupName("springshop-admin")
              .apiInfo(apiInfo());
  }

现在:

 @Bean
  public GroupedOpenApi publicApi() {
      return GroupedOpenApi.builder()
              .group("springshop-public")
              .pathsToMatch("/public/**")
              .build();
  }
  @Bean
  public GroupedOpenApi adminApi() {
      return GroupedOpenApi.builder()
              .group("springshop-admin")
              .pathsToMatch("/admin/**")
              .build();
  }

如果只有一个 Docket ,请将其删除,然后将属性添加到您的application.properties:

springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**

5.4 添加OpenAPI类型的bean,参见示例

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        //大标题
                        .title("Spring Boot中使用Swagger3构建RESTful APIs")
                        // 描述
                        .description("后台API接口")
                        // 版本号
                        .version("v0.0.1")
                        // 作者
                        .contact(new Contact().name("yaoyong").url("http://localhost:8080/swagger").email("swagger@qq.com"))
                        //许可
                        .license(new License().name("The Apache License, Version 2.0").url("http://www.apache.org/licenses/LICENSE-2.0.html")))
                //外部文档
                .externalDocs(new ExternalDocumentation()
                        .description("官方文档")
                        .url("http://springdoc.org"));
    }

效果: 

6.添加一个controller试试看

 6.1 模拟一个具有添删改查功能的接口

@RestController
@RequestMapping(value = "swagger")
@Tag(name = "swagger演示controller", description = "模拟添删改查接口,生成接口文档")
public class SwaggerDemoController {
    public static Integer id = 1;
    public static Map<Integer, User> users = new HashMap();


    @PostMapping("add")
    @Operation(summary = "添加用户接口", description = "可以用来新增用户")
    @Parameter(name = "user", description = "用户实体模型")
    public ResponseEntity<Map> addUser(@RequestBody User user) {
        users.put(id++, user);
        return ResponseEntity.ok(users);
    }

    @DeleteMapping("delete/{id}")
    @Operation(summary = "删除用户接口", description = "可以用来删除用户")
    @Parameter(name = "id", description = "用户ID")
    public ResponseEntity<Map> deleteUserById(@PathVariable(name = "id") Integer id) {
        users.remove(id);
        return ResponseEntity.ok(users);
    }

    @PutMapping("update")
    @Operation(summary = "修改用户接口", description = "可以用来修改用户")
    @Parameter(name = "id", description = "用户ID", in = ParameterIn.QUERY)
    @Parameters({@Parameter(name = "userName", description = "用户名", in = ParameterIn.QUERY),
            @Parameter(name = "passWord", description = "密码", in = ParameterIn.QUERY)})
    @io.swagger.v3.oas.annotations.parameters.RequestBody(content = {@Content(mediaType = "application/x-www-form-urlencoded")})
    public ResponseEntity<Map> updateUser(Integer id, String userName, String passWord) {
        User user = users.get(id);
        user.setUserName(userName);
        user.setPassWord(passWord);
        users.put(id, user);
        return ResponseEntity.ok(users);
    }

    @GetMapping("find")
    @Operation(summary = "查找用户接口", description = "可以用来查询用户")
    @Parameter(name = "id", description = "用户ID")
    public ResponseEntity<User> findUserById(Integer id) {
        User user = users.get(id);
        return ResponseEntity.ok(user);
    }

}

@Data
@Schema(description = "用户实体模型")
class User {
    @Schema(description = "用户名")
    private String userName;

    @Schema(description = "密码")
    private String passWord;
}

6.2 启动项目查看api

6.3 添加一个用户

 6.4 修改一个用户

6.5 查找一个用户 

6.6 删除一个用户

ok, 现在你已经可以在项目中使用它了!

7.自定义页面布局 

springdoc:
  swagger-ui:
    layout: BaseLayout

 如果自己前端比较六,可以自己写,访问http://localhost:8080/v3/api-docs

只需要解析这个json串 ,渲染到自己写的ui界面