【项目精讲】Swagger接口文档以及使用方式

Swagger

介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(https://swagger.io/)

1. 前后端分离开发，有利于团队合作
2. 接口的文档在线自动生成，降低后端开发人员编写接口文档的负担
3. 功能测试

如何使用

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案，项目中用knife4j框架生成swagger接口文档

1. pom.xml中添加依赖

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

2. 配置类中加入knife4j的相关配置——WebMvcConfiguration.java

/**
     * 通过knife4j生成接口文档
     * @return
*/
    @Bean
    public Docket docket() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("苍穹外卖项目接口文档")
                .version("2.0")
                .description("苍穹外卖项目接口文档")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

3. 设置静态资源映射，否则接口文档页面无法访问——WebMvcConfiguration.java

/**
 * 设置静态资源映射
 * addResourceHandlers是重写了父类的方法
 * 告诉Spring MVC框架，如何处理静态资源请求
 * @param registry
 */
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
    log.info("开始设置静态资源映射…");
    //  其中/doc.html请求会被映射到类路径META-INF/resources/目录下的资源
    registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}

4. 通过注解控制生成的接口文档
   1. @Api：用在类上，例如Controller，表示对类的说明
   2. @ApiOperation：用在方法上，例如Controller的方法，说明方法的用途、作用
   3. @ApiModel：用在类上，例如entity、DTO、VO
   4. @ApiModelProperty：用在属性上，描述属性信息

参考

https://www.bilibili.com/video/BV1TP411v7v6/?spm_id_from=333.337.search-card.all.click&vd_source=0d2a9b4260ce977e642d073c6ee2260d