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

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. JVM调优—Jstack

    Java命令学习系列(二)——Jstack   jstack是java虚拟机自带的一种堆栈跟踪工具. 功能 jstack用于生成java虚拟机当前时刻的线程快照.线程快照是当前java虚拟机内每一条线 ...

  2. 什么是VR中的vection?

    Vection是VR领域的一个专有名词,其义指“在虚拟现实中给人带来‘移动’(self-motion)感觉的认知因素”1.也就是说,vection就是指那些给玩家带来“我正在这个虚拟环境中移动”这种感 ...

  3. 开发电商平台用PHP语言和JAVA语言有什么区别?哪种语言更好?

    现在很多行业都通过电子商务拓展业务,所以商城系统开发成为很多企业的刚性需求.一般有一点技术基础的客户应该知道目前商城系统开发主流语言有两个,PHP和Java.那么很多客户朋友会纠结是选择哪个语言开发好 ...

  4. [LeetCode] 470. Implement Rand10() Using Rand7()

    Given a function rand7 which generates a uniform random integer in the range 1 to 7, write a functio ...

  5. [LeetCode] 824. Goat Latin

    Description A sentence S is given, composed of words separated by spaces. Each word consists of lowe ...

  6. MongoDB 学习笔记之 索引

    索引: db.media.createIndex({"Tracklist": 1}) 1表示升序 -1表示降序 我们要着重看一下对数组创建索引的情况. 构建一个集合:db.medi ...

  7. MySql自定义函数-关于保留小数位的特殊需求

    背景 昨天,关于价格详情接口又来了一个小需求,而且有点特别.价格显示:改为保留两位小数,没错,就是保留两位小数.大家是不是想说这没啥特别的...数据库都有函数搞定了.例如四舍五入的ROUND(x,d) ...

  8. yii2 rules 规则

    required : 必须值验证属性 [['字段名'],required,'requiredValue'=>'必填值','message'=>'提示信息']; #说明:CRequiredV ...

  9. js悬浮、回到顶部

    <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8&quo ...

  10. 面试官,不要再问我“Java GC垃圾回收机制”了

    Java GC垃圾回收几乎是面试必问的JVM问题之一,本篇文章带领大家了解Java GC的底层原理,图文并茂,突破学习及面试瓶颈. 楔子-JVM内存结构补充 在上篇<JVM之内存结构详解> ...