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

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

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

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

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

YAPI

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

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

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

特性

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

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

• 类似 postman 的接口调试

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

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

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

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

主页面

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 的数据格式。

我们会配置下面的内容，告诉 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 文档

数据字典

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 管理

数据字典

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

参考资料