Swagger：在线接口文档

Swagger介绍及使用

官网:https://swagger.io/

介绍

使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面。

Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

使用方式

1.导入 knife4j 的maven坐标

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

2.在配置类中加入 knife4j 相关配置,设置静态资源映射，否则接口文档页面无法访问

@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {
    /**
     * 通过knife4j生成接口文档
     *
     * @return
     */
    @Bean
    public Docket docket() {
        log.info("准备生成接口文档..");
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("开心餐厅项目接口文档")//文章标题
                .version("2.0")//版本号
                .description("开心餐厅项目接口文档")//文档名称
                .build();//创建
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName("管理端接口")//分组名称
                .apiInfo(apiInfo)//api的信息
                .select()//设置扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller"))// 扫描指定包下的接口，最为常用
                .paths(PathSelectors.any())// 满足条件的路径，该断言总为true
                .build();
        return docket;
    }
    /**
     * 设置静态资源映射
     *
     * @param registry
     */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        log.info("开始设置静态资源映射....");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

3.接口文档的访问路径：http://ip:port/doc.html

例如我的tomcat服务器的端口号为8080，同时在本地运行，访问的路径就为http://localhost:8080/doc.html

接口测试

Swagger常用注解

注解	说明
@Api	用在类上，例如Controller，表示对类的说明
@ApiModel	用在类上，例如entity、DTO、VO
@ApiModelProperty	用在属性上，描述属性信息
@ApiOperation	用在方法上，例如Controller的方法，说明方法的用途、作用