Swagger的使用方法

1.引入依赖

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

2.配置Swagger2

@Configuration
@EnableSwagger2
//3.0.0以上版本无需加该注解
public class Swagger2Configuration{
    
    @Bean
    public Docket docket(){
    
        
        return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(new ApiInfoBuilder()
                 .title("用户管理系统")
                 .description("用户管理系统接口文档")
                 .version("3.3")
                 .contact(new Contact("公司名","http://www.baidu.com","[email protected]"))
                  .build()
                 )
         .select()
          //Controller所在的包
         .api(RequestHandlerSelectors.basePackage("com.xxx.controller"))
         .build();
    }
}

3.访问API文档页面

在浏览器中访问 http://localhost:8080/projectName/swagger-ui/index.html 即可。

4.常用注解

实例写一个Controller类

@RestController
@RequestMapping("/user")
@Api(tags="用户相关操作接口")
public class UserController{
    
    @ApiOperation("根据用户Id进行查询")
    @ApiImplicitParam(name="id",value="用户id",requires=true,example="33",defaultValue="444") 
    @PostMapping("/selectById")
    public String selectById(Integer id){
    
        ...
            return "selectById";
    }
}

如果传参是一个实体类对象User，栗子：

@ApiModel
public class User{
    
    //对Integer等数字类型需要赋默认值，否则报错
    @ApiModelProperty(value="用户ID",example="1")
    private Integer userId;
    @ApiModelProperty(value="用户名")
    private String userName;
    @ApiModelProperty(value="用户密码")
    private String password;
    @ApiModelProperty(value="用户地址")
    private String address;
    ...(setter,getter and toString)
}

提取知识点：

@Api：用于设置模块接口名

@ApiOperation(...)：用于设置功能方法名

@ApiImplicitParam：用于描述方法参数含义

其下一些参数描述：

​ ①name：形参名

​ ②value：描述含义

​ ③required：是否为必填项

​ ④example：样例值

​ ⑤defaultValue：默认值

@ApiImplicitParams：使用数组格式存储多个参数描述

@ApiModel：用在实体类上，用于实体类在API文档上的说明。

@ApiModelProperty：用于说明实体类中属性在API文档上的解释说明。