【项目精讲】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
*/@Beanpublic 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