Swagger解决你手写API接口文档的痛
- 2019 年 11 月 4 日
- 筆記
首先，老规矩，我们在接触新事物的时候, 要对之前学习和了解过的东西做一个总结。
01
痛 苦
不做、不行
之前，前后端分离的系统由前端和后端不同的编写，我们苦逼的后端工程师会把自己已经写完的API接口，写一个接口文档给到我们前端工程师，前端工程师拿到接口文档之后，根据接口文档规定的URL、请求方式(POST或GET)、请求参数、返回结果(成功或失败，失败时，返回的状态分别代表什么意思)，来对接我们后端提供的API接口，如果提供的接口文档有问题，那么同样的，前端对接时，也会出现问题，前端会说是后端提供的接口文档的问题，后端觉得我可能程序更新了，没有及时更新接口文档。其实，不管是前端还是后端，都希望有一个好的接口文档，能随着程序的迭代不断更新的接口文档。
而写接口文档这种没有技术含量又苦恼的事儿，对于后端来说无疑是噩梦一般，API接口少，没几个，可能半个点一个点就完事儿了，如果API接口很多，比如说整个订单系统的接口，写接口文档这种事儿可能会耗上一天，两天，甚至三天，最后写完还不一定是对的，那个痛啊。
02
邂 逅
有痛点、抛出来
之前写API文档的方式各种各样，wiki、word、excel、text等等各种方式，万物皆可盘。
比如word：
对，word要把目录给人家定义好，要不会被喷的。
再比如excel：
还有text：
千篇一律， 能不能再乱一点，前端已经提这40米的大砍刀在向你走来。
有没有自动生成API文档的插件呢？答：有，还自带各种插件
关于SwaggerSwagger是一个功能强大且易于使用的API开发人员工具套件，适用于团队和个人，可在整个API生命周期（从设计和文档到测试和部署）中进行开发。
Swagger由开放源代码，免费和市售工具共同组成，它使任何人（从技术工程师到街头智能产品经理）都可以构建每个人都喜欢的惊人API。
Swagger由SmartBear Software构建，后者是团队软件质量工具的领导者。SmartBear落后于软件领域的一些知名公司，包括Swagger，SoapUI和QAComplete。
在Swagger官网上提供了几种工具，可以通过集成的方式来实现我们想要的效果。
Swagger Inspector:类似postman的一种API调试工具，可以点击URL，查看如何使用。https://swagger.io/docs/swagger-inspector/how-to-use-swagger-inspector/。
Swagger Codegen:是一个开源代码生成器，可直接从Swagger定义的RESTful API构建服务器存根和客户端SDK。Swagger Codegen的源代码可以在GitHub中找到，点击URL，查看如何使用。https://swagger.io/docs/open-source-tools/swagger-codegen/。
Swagger Editor:是一个开源编辑器，用于设计，定义和记录Swagger规范中的RESTful API，点击URL查看如何使用，https://swagger.io/docs/open-source-tools/swagger-editor/
Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目，点击URL查看如何使用，https://swagger.io/docs/open-source-tools/swagger-ui/usage/installation/
03
接 触
收入囊中
Swagger是什么我们已经介绍完了，下面我们通过代码示例来讲解如何与Springboot结合使用。
1、引入Swagger相关jar包(Springboot相关jar自行引入)
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
2、创建启动类，设置启动参数，首先创建一个class，命名为SwaggerApplication，其中managerPackage为Swagger要管理的包目录，比如com.user.api.controller，从header获取参数名为Authorization的值，可以用于验证权限(如果显示不完整请左右滑动查看全部)。
1 /** 2 * Swagger2配置类 3 * 在与spring boot集成时，放在与Application.java同级的目录下。 4 * 通过@Configuration注解，让Spring来加载该类配置。 5 * 再通过@EnableSwagger2注解来启用Swagger2。 6 */ 7 @Configuration 8 @EnableSwagger2 9 public class SwaggerApplication{ 10 11 @Value(value = "${swagger.manager.package}") 12 private String managerPackage; 13 14 /** 15 * 创建API应用 16 * apiInfo() 增加API相关信息 17 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现， 18 * 本例采用指定扫描的包路径来定义指定要建立API的目录。 19 * 20 * @return 21 */ 22 @Bean 23 public Docket createRestApi(){ 24 ParameterBuilder aParameterBuilder = new ParameterBuilder(); 25 aParameterBuilder 26 .parameterType("header") //参数类型支持header, cookie, body, query etc 27 .name("Authorization") //参数名 28 .defaultValue("Authorization") //默认值 29 .description("token") 30 .modelRef(new ModelRef("string"))//指定参数值的类型 31 .required(false).build(); //非必需，这里是全局配置，然而在登陆的时候是不用验证的 32 List<Parameter> aParameters = new ArrayList<Parameter>(); 33 aParameters.add(aParameterBuilder.build()); 34 return new Docket(DocumentationType.SWAGGER_2) 35 .groupName("v1") 36 .select() 37 .apis(RequestHandlerSelectors.basePackage(basePackage)) 38 .paths(PathSelectors.any()) 39 .build() 40 .apiInfo(apiInfo()) 41 .globalOperationParameters(aParameters); 42 } 43 44 public ApiInfo apiInfo(){ 45 return new ApiInfoBuilder() 46 .title("用户管理API接口文档") 47 .description("用户管理API接口文档") 48 .termsOfServiceUrl("") 49 .contact("sunf") 50 .version("1.0") 51 .build(); 52 } 53 }
3、添加实体类引用，PS：引用只添加DTO、VO，Entity不需要，class头注解@ApiModel，申明该类被Swagger解析，@ApiModelProperty声明各字段属性的含义。
1 @ApiModel(description = "用户信息") 2 @Data 3 public class Users { 4 5 @ApiModelProperty(value = "用户ID") 6 private String id; 7 @ApiModelProperty(value = "用户姓名") 8 private String userName; 9 @ApiModelProperty(value = "年龄") 10 private String age; 11 @ApiModelProperty(value = "性别") 12 private String sex; 13 @ApiModelProperty(value = "地址") 14 private String address; 15 @ApiModelProperty(value = "电话") 16 private String phone; 17 18 }
4、声明Controller，暴漏API接口，如果一个接口没有声明明确的调用方式(POST或GET)method = RequestMethod.POST，Swagger默认会把所有的调用方式都列出来。
@RestController @RequestMapping("/user") @Api(value = "用户相关接口",description = "用户信息") public class UserController { @Autowired private UserService userService; /** * 获取用户详情 * @param userId * @return */ @ApiOperation(value = "获取用户详情", notes = "根据用户ID获取用户详情") @RequestMapping(value = "/get",method = RequestMethod.POST) public Users get(String userId){ return userService.get(userId); } /** * 获取所有用户 * @return */ @ApiOperation(value = "获取所有用户", notes = "获取所有用户列表") @RequestMapping(value = "/getUserAllList",method = RequestMethod.POST) public List<Users> getUserAllList(){ return userService.getUserAllList(); } }
PS:未指定访问方式是这样的
5、到此Swagger的配置基本完成，启动Springboot的服务，访问Swagger内置的web页面，可以看到我们暴漏的所有API和调用方式，访问地址：http://localhost:8081/swagger-ui.html
6、点击获取用户详情的接口，try it out ,可以针对此接口进行访问调试，点击Model可以查看用户实体
7、如果是页面样式不满意，我们可以自定义页面样式，现在github已经有道友分享了自定义的ui，如何使用请查看，https://github.com/caspar-chen/swagger-ui-layer，下图是新的UI，是不是你的菜。
小结：Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码。
微信扫一扫关注我，分享给其他人，一起成长
