swagger3

swagger 用于生成，描述，调用，可视化 RESTFUL风格的web服务。

在swargger2中需要导两个依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

在3,0中只需要导一个包

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2.9.2 中我们主要访问两个地址：

• 文档接口地址：http://localhost:8080/v2/api-docs
• 文档页面地址：http://localhost:8080/swagger-ui.html

现在在 3.0 中，这两个地址也发生了变化：

• 文档接口地址：http://localhost:8080/v3/api-docs
• 文档页面地址：http://localhost:8080/swagger-ui/index.html

3.0 也可以使用之前2版本的注解

swagger使用

1. 导入3.0的包
2. 启动springboot，访问 http://localhost:8080/swagger-ui/index.html

swagger3的配置：

@Configuration
public class SwaggerConfig {

    @Bean
    Docket docket(){
        return new Docket(DocumentationType.OAS_30)
                .select()
//                指定接口所在的包
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
//                这个包下所有方法都要
                .paths(PathSelectors.any())
                .build()
//                设置页面信息
                .apiInfo(new ApiInfoBuilder()
//                        描述
                        .description("项目接口文档")
//                        联系信息
                        .contact(new Contact("waterkid","http://water-kid.cn","xxx@qq.com"))
                        .version("v1.0")
                        .title("silly b")
                        .license("Apache 2.0")
                        .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                        .build());
    }
}

swagger注解：

@Api(tags="")

​ 用在请求的类Controller上，表示对类的说明

​ tags"说明该类的作用，可以在UI界面上看到的注解"

@ApiOperation(value="")

​ 用在请求的方法上，说明方法的用途、作用

​ value=“说明方法的用途、作用”

@ApiImplicitParams

​ 用在请求的方法上，表示一组参数说明

@ApiImplicitParam

​ 指定一个请求参数的各个方面

​ value：参数的汉字说明、解释

​ required：参数是否必须传

​ paramType：参数放在哪个地方

​ header –> 请求头的获取：@RequestHeader

​ query –> 请求参数的获取：@RequestParam

​ path（用于restful接口）–> 请求路径变量的获取：@PathVariable

​ body（不常用）

​ form（不常用）

​ dataType：参数类型，默认String，其它值dataType=“Integer”

​ defaultValue：参数的默认值

@ApiResponses

​ 用在请求的方法上，表示一组响应

@ApiResponse

​ 用在@ApiResponses中，一般用于表达一个错误的响应信息

​ code：数字，例如400

​ message：信息，例如"请求参数没填好"

​ response：抛出异常的类

@ApiModel

​ 主要有两种用途：

​ 用于响应类上，表示一个返回响应数据的信息

​ 入参实体：使用@RequestBody这样的场景， 请求参数无法使用@ApiImplicitParam注解进行描述的时候

@ApiModelProperty

​ 用在属性上，描述响应类的属性

@Api(tags = "user类") // 用在类Controller上，表示对类的说明
@RestController
@RequestMapping("/user")
public class UserController {

    @GetMapping("/{id}")
//    @ApiOperation(value = "查询用户",notes = "详细说明：根据id查询用户")  // 用在方法上，对方法的说明
    @Operation(summary = "查询用户",description = "详细描述")  // swagger3.0
    @ApiImplicitParams({
            /**   paramType：参数类型。 path(路径传递)/query(key/value传递)/body(请求体传递)
             *      name  :  参数名字
             *      value ：  中文解释
             *      required ： 是否必须
             */
            @ApiImplicitParam(paramType = "path",name = "id",value = "用户id",required = true)
    })
    @ApiResponses({// 自定义相应信息  swagger3.0

       @ApiResponse(responseCode = "200",description = "请求成功"),
       @ApiResponse(responseCode = "500",description = "请求失败")
    })
    public String getUserById(@PathVariable("id") int id){
        return "hello";
    }



    @ApiIgnore // 不生成文档
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }


    @PostMapping("/update")
    @ApiImplicitParam(paramType = "path",name = "user",value = "传入的user",required = true)
    public void update(@RequestBody User user){

    }
}

@ApiModel(value = "用户实体类",description = "这个类定义了用户的所有属性")
public class User {
    @ApiModelProperty("用户id")
    private Integer id;
    @ApiModelProperty("用户名")
    private String username;
    private String address;
    ...
}

遇到的问题：

swagger3包导入不成功，将maven仓库中swagger2的包删除后，再导入swagger3

引用：http://www.javaboy.org/2021/0129/springboot-swagger3.html