为我开发的API添加华丽的外衣

在日常开发中,最容易被吐槽的就是代码写的烂,没有注释鬼知道你这个是什么意思啊?

另一个就是文档不齐全,这些接口是干嘛的?参数是什么意思?等等问题。

归根到底还是没有严格的开发规范,最重要的还是要有方便的工具来帮助我们落地这些规范。

今天给大家推荐一个开源API 管理工具,如果还没有用上的感觉看看吧。

YAPI

YApi 是高效、易用、功能强大的 api 管理平台,旨在为开发、产品测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 API,YApi 还为用户提供了优秀的交互体验,开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。

主页: http://yapi.demo.qunar.com/
[1]

GitHubhttps://github.com/YMFE/yapi
[2]

特性

  • 基于 Json5 和 Mockjs 定义接口返回数据的结构和文档,效率提升多倍

  • 扁平化权限设计,即保证了大型企业级项目的管理,又保证了易用性

  • 类似 postman 的接口调试

  • 自动化测试, 支持对 Response 断言

  • MockServer 除支持普通的随机 mock 外,还增加了 Mock 期望功能,根据设置的请求过滤规则,返回期 望数据

  • 支持 postman, har, swagger 数据导入

  • 免费开源,内网部署,信息再也不怕泄露了

主页面

为我开发的API添加华丽的外衣

API 基本信息

为我开发的API添加华丽的外衣

参数和响应

为我开发的API添加华丽的外衣

Swagger

介绍

Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口,可让人和计算机拥有无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger 消除了调用服务时可能会有的猜测。

GitHub: https://github.com/swagger-api
[3]

集成

Spring Boot 中可以使用开源的 starter 包来进行集成会更简单,比如我们用 spring4all 的这个封装,Maven 依赖如下:

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.1.RELEASE</version>
</dependency>

依赖加好后在启动类上加@EnableSwagger2Doc 来启用 Swagger。

使用

使用的话就不具体讲解了,也比较简单,就是在你的接口上加一些注解来描述这个接口是干嘛的就可以了。

默认不加注解也能将你的接口全部显示出来,也就是扫描了你的@RestController 中的方法。

为我开发的API添加华丽的外衣
主页面

为我开发的API添加华丽的外衣
接口列表

有可能会遇到的问题

一般我们会在项目中进行全局的异常处理,当发生错误时,将异常捕获然后转换成固定的格式响应给调用方,这样可以统一 API 的数据格式。

我们会配置下面的内容,告诉 SpringBoot 不要为我们工程中的资源文件建立映射,这样就可以返回纯 JSON 的内容。

spring.resources.add-mappings=false

但是这样的话我们的 swagger-ui.html 就不能访问了,所以需要对 swagger-ui.html 相关的资源单独进行映射。

@Configuration

public class WebAppConfigurer extends WebMvcConfigurationSupport {

@Override

protected void addResourceHandlers(ResourceHandlerRegistry registry) {


registry.addResourceHandler("/swagger-ui.html")

.addResourceLocations("classpath:/META-INF/resources/");

registry.addResourceHandler("/webjars/**")

.addResourceLocations("classpath:/META-INF/resources/webjars/");

super.addResourceHandlers(registry);


}


}

ShowDoc

ShowDoc 是一个非常适合 IT 团队的在线 API 文档、技术文档工具。

主页: https://www.showdoc.cc/
[4]

GitHub: https://github.com/star7th/showdoc
[5]

我们可以用 ShowDoc 来做 API 文档,数据字典,说明文档等用途。可以自己进行部署,个人的话也可以使用官方提供的在线示列。

ShowDoc 支持权限管理,支持 markdown 编辑,支持导出,支持分享等功能。

API 文档

为我开发的API添加华丽的外衣
为我开发的API添加华丽的外衣

数据字典

为我开发的API添加华丽的外衣

CRAP-API

CRAP-API 是完全开源、免费的 API 协作管理系统。提供协作开发、在线测试、文档管理、导出接口、个性化功能定制等功能。

主页: http://api.crap.cn/
[6]

GitHub: https://github.com/EhsanTang/ApiManager
[7]

特性

  • 简单高效的 BUG 管理系统,记录每一次变动

  • 团队协作、权限控制、修改日志

  • 数据库表、markdown、restful、mock、pdf、word

  • 开源 chrome 插件,支持跨域、本地、在线接口调试

  • 系统完全免费、完全开源

API 管理

为我开发的API添加华丽的外衣
新增API

数据字典

数据字典还支持生成 MyBatis 的 XML 文件,生成 Java 的 Entity 对象。

为我开发的API添加华丽的外衣

参考资料

[1]

http://yapi.demo.qunar.com/: http://yapi.demo.qunar.com/

[2]

https://github.com/YMFE/yapi: https://github.com/YMFE/yapi

[3]

https://github.com/swagger-api: https://github.com/swagger-api

[4]

https://www.showdoc.cc/: https://www.showdoc.cc/

[5]

https://github.com/star7th/showdoc: https://github.com/star7th/showdoc

[6]

http://api.crap.cn/: http://api.crap.cn/

[7]

https://github.com/EhsanTang/ApiManager: https://github.com/EhsanTang/ApiManager

热文推荐

RedisTemplate:我不背锅,是你用错了

得亏了它,我才把潜藏那么深的Bug挖出来

惊讶!
缓存刚Put再Get居然获取不到?

好机会,我要帮女同事解决Maven冲突问题

上线前一个小时,dubbo这个问题可把我折腾惨了

为了控制Bean的加载我使出了这些杀手锏

为我开发的API添加华丽的外衣
为我开发的API添加华丽的外衣

为我开发的API添加华丽的外衣

如有收获,点个在看,诚挚感谢

原文 

http://mp.weixin.qq.com/s?__biz=MzIwMDY0Nzk2Mw==&mid=2650321188&idx=1&sn=76fddf121e1c6f37b1d26e104127d5d6

本站部分文章源于互联网,本着传播知识、有益学习和研究的目的进行的转载,为网友免费提供。如有著作权人或出版方提出异议,本站将立即删除。如果您对文章转载有任何疑问请告之我们,以便我们及时纠正。

PS:推荐一个微信公众号: askHarries 或者qq群:474807195,里面会分享一些资深架构师录制的视频录像:有Spring,MyBatis,Netty源码分析,高并发、高性能、分布式、微服务架构的原理,JVM性能优化这些成为架构师必备的知识体系。还能领取免费的学习资源,目前受益良多

转载请注明原文出处:Harries Blog™ » 为我开发的API添加华丽的外衣

赞 (0)
分享到:更多 ()

评论 0

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址