SpringBoot中集成swagger3（OpenAPI）

SpringBoot中集成swagger3（OpenAPI）

---

步骤概括：

1. 导入swagger3 的依赖。
2. SpringBoot版本高于2.4or2.5，在application.yml配置文件中增加mvc配置。
3. 定义swagger配置类。
4. 开始使用。

step1.

在pom.xml中导入swagger3的相关依赖。

   
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-boot-starterartifactId>
            <version>3.0.0version>
        dependency>

如果使用swagger自带ui界面，那么这一个依赖就能够满足需求了。但是想要界面UI元素更丰富一点，可以添加一个UI的依赖，如下：

     
        
        <dependency>
            <groupId>com.github.xiaoymingroupId>
            <artifactId>knife4j-spring-boot-starterartifactId>
            <version>2.0.9version>
        dependency>

引入这个依赖不需要做任何配置，只需要在启动项目的时候，访问地址变为 ： /doc.html 即可。

step2.

步骤2在低版本SpringBoot中不用进行配置，在高版本SpringBoot中，如果不进行mvc路径配置，则会报错，报错为：

Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException

解决这个报错，只需要在 application.yml中配置mvc路径匹配模式即可

  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

step3.

自定义配置类 config/SwaggerConfig.java

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(getApiInfo())
                .groupName("用户模块")
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.com.xx.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    @Bean
    public Docket docketUser(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(getApiInfo())
                .groupName("实体类模块")
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.com.xx.bean.entity"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo getApiInfo(){
        return new ApiInfoBuilder()
                .title("API Documentation By Swagger3!接口文档")
                .description("swagger3")
                .contact(new Contact("Arthur","http://lcoalhost","[email protected]"))
                .version("1.0")
                .license("Apache 2.0")
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }

}

step4.

开始使用，

主要就分为2个大类

在controller里面使用，@Api(tags = “功能模块”) 和 @ApiOperation(“什么请求操作”) .。

参数相关就是 @ApiImplicitParams 和单个参数 @ApiImplicitParam

在实体类里面使用，标注实体类 @ApiModel(“用户实体类”)和标注成员属性 @ApiModelProperty(“用户姓名”)

以下是demo

//User.java
@ApiModel("用户实体类")
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
    @ApiModelProperty("用户id")
    private Integer id;
    @ApiModelProperty("用户姓名")
    private String name;
    @ApiModelProperty("用户年龄")
    private Integer age;
}

//UserController.java
@RestController
@RequestMapping("/user")
@Api(tags = "用户接口类")
public class UserController {
    /***
     * @param user:
     * @return java.lang.String
     */
    @ApiOperation("新增用户")
    @PostMapping("/save")
    public String insertUser(User user){
        return user.getName() + ":"+ user.getAge();
    }

    /**
     *
     * @param name
     * @param age
     * @return java.lang.String
     */
    @ApiOperation("根据姓名和年龄进行查询")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "用户姓名", required = true, paramType = "query"),
            @ApiImplicitParam(name = "age", value = "用户年龄", required = true, paramType = "query")
    })
    @PostMapping("/search")
    public String getUserByNameAndAge(String name, Integer age){
        return name + " : " + age;
    }

    @ApiOperation("根据用户id进行查询")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, paramType = "query")
    @ApiResponses({
            @ApiResponse(code = 408, message = "用户信息错误"),
            @ApiResponse(code = 409, message = "业务信息错误"),
            @ApiResponse(code = 598, message = "请求路径错误"),
    })
    @GetMapping("/id/{id}")
    public JsonResult getUserById(@PathVariable Integer id){
        User timo = new User(id, "timo", 18);
        return new JsonResult(true,"666","查询成功！",timo,null);
    }

    @ApiOperation("删除用户")
    @PostMapping("/delete")
    public User deleteUser(){
        return new User();
    }

}

ps: 集成的是swagger3，但仍然使用的是swagger2的注解。