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

栏目: IT技术 · 发布时间: 1周前

来源: mp.weixin.qq.com

本文转载自:http://mp.weixin.qq.com/s?__biz=MzIwMDY0Nzk2Mw==&mid=2650321188&idx=1&sn=76fddf121e1c6f37b1d26e104127d5d6,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有。

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

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

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

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

YAPI

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

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

GitHub: https://github.com/YMFE/yapi [2]

特性

  • 基于 Json 5 和 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添加华丽的外衣

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


以上所述就是小编给大家介绍的《为我开发的API添加华丽的外衣》,希望对大家有所帮助,如果大家有任何疑问请给我留言,小编会及时回复大家的。在此也非常感谢大家对 码农网 的支持!

关注码农网公众号

关注我们,获取更多IT资讯^_^


为你推荐:

相关软件推荐:

查看所有标签

本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们

Web API的设计与开发

Web API的设计与开发

[日] 水野贵明 / 盛荣 / 人民邮电出版社 / 2017-6 / 52.00元

本书结合丰富的实例,详细讲解了Web API的设计、开发与运维相关的知识。第1章介绍Web API的概要;第2章详述端点的设计与请求的形式;第3章介绍响应数据的设计;第4章介绍如何充分利用HTTP协议规范;第5章介绍如何开发方便更改设计的Web API;第6章介绍如何开发牢固的Web API。 本书不仅适合在工作中需要设计、开发或修改Web API的技术人员阅读,对想了解技术细节的产品经理、运维人......一起来看看 《Web API的设计与开发》 这本书的介绍吧!

在线进制转换器
在线进制转换器

各进制数互转换器

Markdown 在线编辑器
Markdown 在线编辑器

Markdown 在线编辑器

RGB CMYK 转换工具
RGB CMYK 转换工具

RGB CMYK 互转工具