手写Api文档的几个痛点:
- 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。
- 接口返回结果不明确
- 不能直接在线测试接口,通常需要使用工具,比如postman
- 接口文档太多,不好管理
Swagger也就是为了解决这个问题,当然也不能说Swagger就一定是完美的,当然也有缺点,最明显的就是代码移入性比较强。
其他的不多说,想要了解Swagger的,可以去Swagger官网,可以直接使用Swagger editor编写接口文档,当然我们这里讲解的是SpringBoot整合Swagger2,直接生成接口文档的方式。
一、依赖
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>
二、swagger配置类
其实这个配置类,只要了解具体能配置哪些东西就好了,毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径,不然生成的文档扫描不到接口。
1 package org.wlgzs.swagger2.config; 2 3 import org.springframework.context.annotation.Bean; 4 import org.springframework.context.annotation.Configuration; 5 import springfox.documentation.builders.ApiInfoBuilder; 6 import springfox.documentation.builders.PathSelectors; 7 import springfox.documentation.builders.RequestHandlerSelectors; 8 import springfox.documentation.service.ApiInfo; 9 import springfox.documentation.service.Contact; 10 import springfox.documentation.spi.DocumentationType; 11 import springfox.documentation.spring.web.plugins.Docket; 12 import springfox.documentation.swagger2.annotations.EnableSwagger2; 13 14 /** 15 * @author zsh 16 * @company wlgzs 17 * @create 2019-02-13 16:01 18 * @Describe 19 */ 20 @Configuration 21 @EnableSwagger2 22 public class Swagger2 { 23 @Bean 24 public Docket createRestApi() { 25 return new Docket(DocumentationType.SWAGGER_2) 26 .apiInfo(apiInfo()) 27 .select() 28 .apis(RequestHandlerSelectors.basePackage("org.wlgzs.swagger2.controller")) 29 .paths(PathSelectors.any()) 30 .build(); 31 } 32 33 private ApiInfo apiInfo() { 34 return new ApiInfoBuilder() 35 // 设置页面标题 36 .title("使用swagger2构建短视频后端api接口文档") 37 // 设置联系人 38 .contact(new Contact("zsh", "http://www.imooc.com", "XXX@163.com")) 39 // 描述 40 .description("欢迎访问短视频接口文档,这里是描述信息") 41 // 定义版本号 42 .version("1.0").build(); 43 } 44 }
用@Configuration注解该类,等价于XML中配置beans;用@Bean标注方法等价于XML中配置bean。加上注解@EnableSwagger2 表示开启Swagger。
三、restful接口
1 package org.wlgzs.swagger2.controller; 2 3 import io.swagger.annotations.Api; 4 import io.swagger.annotations.ApiImplicitParam; 5 import io.swagger.annotations.ApiOperation; 6 import lombok.extern.log4j.Log4j2; 7 import org.springframework.web.bind.annotation.GetMapping; 8 import org.springframework.web.bind.annotation.PathVariable; 9 import org.springframework.web.bind.annotation.RequestParam; 10 import org.springframework.web.bind.annotation.RestController; 11 12 /** 13 * @author zsh 14 * @company wlgzs 15 * @create 2019-02-13 16:01 16 * @Describe 17 */ 18 @RestController 19 @Log4j2 20 @Api(value = "用户控制类") 21 public class UserController { 22 23 @ApiOperation(value="获取信息", notes="根据id来获取信息") 24 @GetMapping("/id") 25 public String a(@RequestParam(value = "id") String id){ 26 log.info("ok"); 27 return "555"; 28 } 29 30 31 }
四、swagger2文档
启动SpringBoot项目,访问 项目地址/swagger-ui.html
五、swagger注解
swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。
- @Api:修饰整个类,描述Controller的作用
- @ApiOperation:描述一个类的一个方法,或者说一个接口
- @ApiParam:单个参数描述
- @ApiModel:用对象来接收参数
- @ApiProperty:用对象接收参数时,描述对象的一个字段
- @ApiResponse:HTTP响应其中1个描述
- @ApiResponses:HTTP响应整体描述
- @ApiIgnore:使用该注解忽略这个API
- @ApiError :发生错误返回的信息
- @ApiImplicitParam:一个请求参数
- @ApiImplicitParams:多个请求参数