Swagger-简单使用

零、本文纲要

• 一、 Swagger

1. Swagger介绍
2. knife4j

• 二、 Swagger快速入门

1. 导入knife4j相关依赖
2. 导入knife4j相关配置类
3. 设置静态资源
4. 放行对应请求路径

• 三、 Swagger常用注解

1. 常用注解
2. 注解使用案例
3. 访问在线接口文档

一、 Swagger

1. Swagger介绍

使用Swagger需要按照规范去定义接口，以及接口相关信息。
通过Swagger衍生项目和工具，可以生成各种格式接口文档，以及在线接口调试页面等。

2. knife4j

knife4j是Java MVC框架继承Swagger生成Api文档的增强解决方案。

二、 Swagger快速入门

1. 导入knife4j相关依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

2. 导入knife4j相关配置类
3. 设置静态资源

添加@EnableSwagger2、@EnableKnife4j注解
设置Docket第三方Bean

@Slf4j
@Configuration
@EnableSwagger2 // 开启对Swagger的支持
@EnableKnife4j // 开启对Knife4j的支持（Swagger增强）
public class WebMvcConfig extends WebMvcConfigurationSupport {

    ... ...
    
    @Bean
    public Docket createRestApi(){
        // 文档类型
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo()
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.stone.project.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("项目名称")
                .version("1.0")
                .description("某某项目接口文档")
                .build();
    } 
    
    /**
     * 配置静态资源映射的方法：Spring Boot 默认静态页面映射是在 /static、/public 路径下，此处自定义
     * @param registry 资源映射处理对象
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        ... ...
        // 此处配置放行的资源就是Swagger框架生成的静态页面
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
    ... ...

}

4. 放行对应请求路径

如果设置了Filter对请求路径进行拦截过滤，此处需要进行放行。

/**
 * 检查用户是否已经登录的过滤器
 */
@Slf4j
@WebFilter(filterName = "loginCheckFilter", urlPatterns = "/*")
public class LoginCheckFilter implements Filter {

    @Override
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain)
            throws IOException, ServletException {
        ... ...
        // 定义不需要处理的请求路径
        String[] urls = new String[]{
                ...,
                // 添加Swagger相关的请求路径，予以放行
                "/doc.html",
                "/webjars/**",
                "/swagger-resources",
                "/v2/api-docs"
        };
        ... ...
    }

三、 Swagger常用注解

1. 常用注解

注解	说明
@Api	用在请求的类上，如Controller，表示对类的说明
@ApiModel	用在类上，通常是实体类Entity，表示一个返回响应数据的信息
@ApiModelProperty	用在属性上，描述响应类的属性
@ApiOperation	用在请求的方法上，说明方法的用途、作用
@ApiImplicitParams	用在请求的方法上，表示一组参数说明
@ApiImplicitParam	用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

2. 注解使用案例

• ① @ApiModel与@ApiModelProperty使用

/**
 * 套餐
 */
@Data
@ApiModel("套餐")
public class Setmeal implements Serializable {
    ... ...
    @ApiModelProperty("主键")
    private Long id;
    ... ...
}

• ② @Api使用

/**
 * 套餐管理
 */
@Slf4j
@RestController
@RequestMapping("/setmeal")
@Api(tags = "套餐相关接口")
public class SetmealController {
    ... ...
}

• ③@ApiOperation与@ApiImplicitParams与@ApiImplicitParam使用

/**
* 套餐分页查询
* @param page 当前页码
* @param pageSize 页容量
* @param name 套餐名称
* @return 分页结果
*/
@GetMapping("/page")
@ApiOperation(value = "套餐分页查询接口")
@ApiImplicitParams({
    @ApiImplicitParam(name = "page", value = "页码", required = true),
    @ApiImplicitParam(name = "pageSize", value = "每页记录数", required = true),
    @ApiImplicitParam(name = "name", value = "套餐名称", required = false)
})
public R<Page<SetmealDto>> page(int page, int pageSize, String name){
    ... ...
}

3. 访问在线接口文档

启动对应项目：http://localhost:8080/doc.html，访问doc.html文档即可。

四、结尾

以上即为Swagger-简单使用的全部内容，感谢阅读。