Swagger 使用记录

4 minute
CS
,

注：本记录配合 Spring 进行使用。

Swagger 依赖

 1<!-- swagger所需依赖 -->
 2<dependency>
 3    <groupId>io.springfox</groupId>
 4    <artifactId>springfox-swagger2</artifactId>
 5    <version>2.6.1</version>
 6</dependency>
 7<dependency>
 8    <groupId>io.springfox</groupId>
 9    <artifactId>springfox-swagger-ui</artifactId>
10    <version>2.6.1</version>
11</dependency>

Swagger 配置

 1// SwaggerConfig.java
 2@Configuration
 3@EnableSwagger2
 4public class SwaggerConfig {
 5    @Bean
 6    public Docket createRestApi() {
 7        return new Docket(DocumentationType.SWAGGER_2)
 8                .apiInfo(apiInfo())
 9                .select()
10                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
11                .paths(PathSelectors.any())
12                .build();
13    }
14
15    // 基本信息的配置，信息会在api文档上显示
16    private ApiInfo apiInfo() {
17        return new ApiInfoBuilder()
18                .title("jzh测试的接口文档")
19                .description("xx相关接口的文档")
20                .termsOfServiceUrl("http://localhost:7777")
21                .version("1.0")
22                .build();
23    }
24}

访问 http://localhost:7777 即可查看文档界面。

Swagger 使用

注解用途

@Api

使用在类上，表明是 swagger 资源，@API 拥有两个属性: value、tags，源码如下：

1//If tags is not used,this value will be used to set the tag for the operations described by this resource. Otherwise, the value will be ignored.
2String value() default "";
3
4//Tags can be used for logical grouping of operations by resources or any other qualifier.
5String[] tags() default {""};

生成的 api 文档会根据 tags 分类，如果 tags 未被使用，那么 value 将被当作 tag 使用（value 一般用于描述该类的作用，但不能有多个值）。

@ApiOperation

使用于在方法上，表示一个请求的操作。

  • value：用于方法描述
  • notes：用于提示内容
  • tags：可以重新分组（视情况而用）

@ApiParam

使用在方法上或者参数上。

  • name：参数名
  • value：参数说明
  • required：是否必填

@ApiModel

使用在类上，表示对类进行说明。

  • value：表示对象名
  • description：描述

@ApiModelProperty

使用在方法，字段上，表示对 model 属性的说明或者数据操作更改。

  • value：字段说明
  • name：重写属性名字
  • dataType：重写属性类型
  • required：是否必填
  • example：举例说明
  • hidden：隐藏

具体使用

 1// SwaggerTest.java
 2@RestController
 3@RequestMapping("/swagger")
 4@Api(tags = {"测试swagger", "用户基本操作"})
 5public class SwaggerTest {
 6    @ApiOperation(value = "新增用户")
 7    @GetMapping("/adduser/{userName}/{userPwd}")
 8    public SwaggerUser addUser(@PathVariable @ApiParam(value = "用户名", required = true) String userName,
 9                        @PathVariable @ApiParam(value = "密码", required = true) String userPwd) {
10        return new SwaggerUser(new Random().nextInt(100), userName, userPwd);
11    }
12}

 1// SwaggerUser.java
 2@Data
 3@AllArgsConstructor
 4@NoArgsConstructor
 5@ToString
 6public class SwaggerUser {
 7    @ApiModelProperty(value = "用户ID")
 8    private Integer userId;
 9    @ApiModelProperty(value = "用户名")
10    private String userName;
11    @ApiModelProperty(value = "用户密码")
12    private String userPwd;
13
14}