首先,老规矩,我们在接触新事物的时候, 要对之前学习和了解过的东西做一个总结。

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的值,可以用于验证权限(如果显示不完整请左右滑动查看全部)。

/** * Swagger2配置类 * 在与spring boot集成时,放在与Application.java同级的目录下。 * 通过@Configuration注解,让Spring来加载该类配置。 * 再通过@EnableSwagger2注解来启用Swagger2。 */@Configuration@EnableSwagger2public class SwaggerApplication{  @Value(value = "${swagger.manager.package}")  private String managerPackage;  /**   * 创建API应用   * apiInfo() 增加API相关信息   * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,   * 本例采用指定扫描的包路径来定义指定要建立API的目录。   *   * @return   */  @Bean  public Docket createRestApi(){    ParameterBuilder aParameterBuilder = new ParameterBuilder();    aParameterBuilder        .parameterType("header") //参数类型支持header, cookie, body, query etc        .name("Authorization") //参数名        .defaultValue("Authorization") //默认值        .description("token")        .modelRef(new ModelRef("string"))//指定参数值的类型        .required(false).build(); //非必需,这里是全局配置,然而在登陆的时候是不用验证的    List<Parameter> aParameters = new ArrayList<Parameter>();    aParameters.add(aParameterBuilder.build());    return new Docket(DocumentationType.SWAGGER_2)        .groupName("v1")        .select()        .apis(RequestHandlerSelectors.basePackage(basePackage))        .paths(PathSelectors.any())        .build()        .apiInfo(apiInfo())        .globalOperationParameters(aParameters);  }  public ApiInfo apiInfo(){    return new ApiInfoBuilder()        .title("用户管理API接口文档")        .description("用户管理API接口文档")        .termsOfServiceUrl("")        .contact("sunf")        .version("1.0")        .build();  }}

3、添加实体类引用,PS:引用只添加DTO、VO,Entity不需要,class头注解@ApiModel,申明该类被Swagger解析,@ApiModelProperty声明各字段属性的含义。

@ApiModel(description = "用户信息")@Datapublic class Users {  @ApiModelProperty(value = "用户ID")  private String id;  @ApiModelProperty(value = "用户姓名")  private String userName;  @ApiModelProperty(value = "年龄")  private String age;  @ApiModelProperty(value = "性别")  private String sex;  @ApiModelProperty(value = "地址")  private String address;  @ApiModelProperty(value = "电话")  private String phone;}

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,则可以通过扫描代码去生成这个描述文件,连描述文件都不需要再去维护了。所有的信息,都在代码里面了。代码即接口文档,接口文档即代码。

微信扫一扫关注我,分享给其他人,一起成长

 

Swagger解决你手写API接口文档的痛的更多相关文章

  1. Api接口文档管理工具,你知道哪些呢?

    上周看到有人在我的Github开源项目中提了个issue,说是否考虑接入swagger.那今天我就用swagger与其他接口文档工具做对比,同时说说Api接口文档工具的那点事.如今,在前后端分离开发的 ...

  2. Swagger 生成 PHP API 接口文档

    Swagger 生成 PHP API 接口文档 Lumen微服务生成Swagger文档 1.概况 有同学反馈写几十个接口文档需要两天的工作量, 随着多部门之间的协作越来越频繁, 维护成本越来越高, 文 ...

  3. spring boot使用swagger生成api接口文档

    前言 在之前的文章中,使用mybatis-plus生成了对应的包,在此基础上,我们针对项目的api接口,添加swagger配置和注解,生成swagger接口文档 具体可以查看本站spring boot ...

  4. SpringBoot + Swagger2 自动生成API接口文档

    spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口.这些接口不但会服务于传统的web端(b/s),也会服务于移动端 ...

  5. 构建标准OpenStack API接口文档

    1.构建API接口文档标准参考: http://docs.openstack.org/contributor-guide/api-guides.html 2.构建API接口文档步骤参考下面的Patch ...

  6. 整合swagger2生成Restful Api接口文档

    整合swagger2生成Restful Api接口文档 swagger Restful文档生成工具 2017-9-30 官方地址:https://swagger.io/docs/specificati ...

  7. Spring Boot从入门到精通(十一)集成Swagger框架,实现自动生成接口文档

    Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.Swagger 是一组开源项目,其中主要要项目如下: Swagger-tools:提供各种与S ...

  8. api(接口)文档管理工具

    api(接口)文档管理工具 欢迎光临:博之阅API管理平台  ,做为一个app开发者,还没有用到api管理工具,你就OUT了 点击进入:程序员精华博客大全  

  9. 智表ZCELL产品V1.4.0开发API接口文档 与 产品功能清单

    为了方便大家使用ZCELL,应网友要求,整理编写了相关文档,现与产品一起同步发布,供大家下载使用,使用过程中如有疑问,请与我QQ联系. 智表(ZCELL)V1.4.0版本  功能清单文档下载地址: 功 ...

随机推荐

  1. 痞子衡嵌入式:飞思卡尔i.MX RTyyyy系列MCU特性那些事(5)- 划时代新品RT1170

    大家好,我是痞子衡,是正经搞技术的痞子.今天痞子衡给大家介绍的是飞思卡尔i.MX RTyyyy系列MCU的划时代新品i.MXRT1170. 自2017年开始,每年的6月25日恩智浦都会在北京举行微控制 ...

  2. python简单爬虫(爬取pornhub特定关键词的items图片集)

    请提前搭好梯子,如果没有梯子的话直接403. 1.所用到的包 requests: 和服务器建立连接,请求和接收数据(当然也可以用其他的包,socket之类的,不过requests是最简单好用的) Be ...

  3. Thread线程类

    设置线程名 查看线程名是很简单的,调用Thread.currentThread().getName()即可. public class MyThreadDemo { public static voi ...

  4. 【柠檬班】jmeter 不写代码,秒秒钟提取动态列表最后一个值

    在用jmeter做接口测试时,我们经常会遇到,一个接口返回一个json串,在这个json串中,某个节点的值是一个列表,而且这个列表的长度是动态变化的.如:   获取用户列表,用户信息是个列表,类似的接 ...

  5. 一个简单的Eclipse调试Debug流程(四)

    本文链接:https://blog.csdn.net/u011781521/article/details/55000066    http://blog.csdn.net/u010075335/ar ...

  6. java第3天:Scanner,Random,ArrayList

    第一章:Scanner从入门到放弃 1 API的概述和使用步骤 API简称应用程序编程接口,是JDK给我们提供好的可以直接使用的类和方法,是程序员随手使用的字典. *** 2 Scanner的概述 2 ...

  7. Github | 吴恩达新书《Machine Learning Yearning》完整中文版开源

    最近开源了周志华老师的西瓜书<机器学习>纯手推笔记: 博士笔记 | 周志华<机器学习>手推笔记第一章思维导图 [博士笔记 | 周志华<机器学习>手推笔记第二章&qu ...

  8. jsp隐含对象(内置对象)

    JSP共有以下9个内置的对象: request HttpServletRequest类的实例,用户端请求,此请求会包含来自GET/POST请求的参数 response HttpServletRespo ...

  9. 单引号、双引号与定界符——PHP

    单引号与双引号 单引号和双引号在echo输出时的区别 echo输出时,如果使用单引号,那么echo会把单引号之间的全部内容当成普通字符串输出,不能识别变量和转义字符(单引号串中的内容总被认为是普通字符 ...

  10. 无 PowerShell.exe 执行 Empire 的几种姿势

    在实战中,Empire成为域渗透.后渗透阶段一大利器,而Empire是一个Powershell RAT,所以PowerShell必须要能运行Empire中几乎所有的启动方法都依赖于使用PowerShe ...