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

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

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

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

今天给你们推荐一个开源的API管理工具，若是尚未用上的感受看看吧。

YAPI

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

主页：http://yapi.demo.qunar.com/

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

特性

• 基于 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

集成

在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/

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

咱们能够用ShowDoc来作API文档，数据字典，说明文档等用途。能够本身进行部署，我的的话也可使用官方提供的在线示列。

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

API文档

数据字典

CRAP-API

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

主页：http://api.crap.cn/

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

特性

• 简单高效的BUG管理系统，记录每一次变更
• 团队协做、权限控制、修改日志
• 数据库表、markdown、restful、mock、pdf、word
• 开源chrome插件，支持跨域、本地、在线接口调试
• 系统彻底免费、彻底开源

API管理

新增API

数据字典

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