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

网友投稿 309 2022-06-07


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

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

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

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

YAPI

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

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

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

特性

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>
<https://p.download-x.com/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://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

特性

新增API

数据字典

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


版权声明:本文内容由网络用户投稿,版权归原作者所有,本站不拥有其著作权,亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容,请联系我们jiasou666@gmail.com 处理,核实后本网站将在24小时内删除侵权内容。

上一篇:RestFul API 统一格式返回 + 全局异常处理(restful和webservice区别)
下一篇:基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (上篇)
相关文章

 发表评论

暂时没有评论,来抢沙发吧~