Swagger处理你手写API接口文档的痛

 

　　起首，老例子，我们在打仗新事物的时刻, 要对之前进修和相识过的东西做一个总结。

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,则能够经由过程扫描代码去生成这个形貌文件，连形貌文件都不须要再去保护了。一切的信息，都在代码内里了。代码即接口文档，接口文档即代码。

 

微信扫一扫关注我，分享给其他人，一同生长