Swagger使用教程

访问地址 http://localhost:8088/context-path/swagger-ui/index.html

1.引入依赖

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

2.编写配置类

@EnableOpenApi
@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("Swagger3接口文档")
            .description("更多请咨询服务开发者天宇宇宇宇宇a")
            .contact(new Contact("天宇宇宇宇宇a", "http://tianyuzhu.top/", "1659770218@QQ.COM"))
            .version("1.0")
            .build();
    }
}

3.Controller模板

@Controller
@Api(value = "/", tags = "用户登录Controller")
public class LoginController {

    @ApiOperation(value = "login", notes = "登录方法", response = String.class)
    @PostMapping(value = "/user/login")
    public String login(
        @ApiParam(name = "用户名", value = "username", required = true) @RequestParam(value = "username") String username,
        @ApiParam(name = "密码", value = "password", required = true) @RequestParam(value = "password") String password
    ){

        return "dashboard";
    }
}

4.实体类模板

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "员工实体类")
public class Employee {

    @ApiModelProperty(value = "员工ID", example = "0", required = true)
    private Integer id;
    @ApiModelProperty(value = "员工名称", example = "张三", required = true)
    private String lastName;
    @ApiModelProperty(value = "员工邮箱", example = "xxx@xx.com", required = true)
    private String email;
    //1 male, 0 female
    @ApiModelProperty(value = "员工性别", example = "0 男 | 1 女", required = true)
    private Integer gender;
    @ApiModelProperty(value = "员工所在的部门", example = "开发部", required = true)
    private Department department;
    @ApiModelProperty(value = "员工生日", example = "2020-11-28", required = true)
    private Date birth;

}

5.常用注解

5.1 类

@Api()：表示这个类是 swagger 资源

• tags：表示说明内容，只写 tags 就可以省略属性名
• value：同样是说明，不过会被 tags 替代，没卵用

5.2 方法

@ApiOperation() ：对方法的说明，注解位于方法上

• value：方法的说明
• notes：额外注释说明
• response：返回的对象
• tags：这个方法会被单独摘出来，重新分组，若没有，所有的方法会在一个Controller分组下

5.3 方法入参

@ApiParam()：对方法参数的具体说明，用在方法入参括号里，该注解在post请求参数时，参数名不显示

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

@ApiImplicitParam对方法参数的具体说明，用在方法上@ApiImplicitParams之内，该注解在get,post请求参数时，参数名均正常显示

• name 参数名称
• value 参数的简短描述
• required 是否为必传参数
• dataType 参数类型，可以为类名，也可以为基本类型（String，int、boolean等）指定也不起作用，没卵用
• paramType 参数的传入（请求）类型，可选的值有path, query, body, header or form。

5.4 实体类

@ApiModel描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

• value model的别名，默认为类名
• description model的详细描述

@ApiModelProperty描述一个model的属性

• value 属性简短描述
• example 属性的示例值
• required 是否为必须值

5.5 header参数

@ApiImplicitParams({      @ApiImplicitParam(paramType="header",name="USERTOKEN",dataType="String",required=true,value="用户token")
                   })

5.6 file入参

需要使用@RequestPart 注解

@ApiOperation(value = "上传文件接口",notes = "上传文件接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "上传人")
})
@PostMapping(value = "/uploadFile")
public String uploadFile(@RequestParam("name") String name,@RequestPart("file") MultipartFile file){

}

6.拦截器放行

若项目中有使用拦截器，放行以下路径

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Autowired
    TokenInterceptor tokenInterceptor;

    /**
     * 拦截器
     * @param registry
     */
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 注册token拦截器
        registry.addInterceptor(tokenInterceptor)
            .addPathPatterns("/**")
            .excludePathPatterns("/**/swagger-ui/**")
            .excludePathPatterns("/**/swagger-resources/**")
            .excludePathPatterns("/**/v3/**")
            ;
    }
}

7.统一返回值问题

若项目中使用了统一返回值的包装类例如BaseResponse，方法返回时加上泛型，

例如返回 BaseResponse<User>