Swagger+YApi打造统一API接口管理平台

七路灯
1,320 阅读3分钟

本文已参与「新人创作礼」活动，一起开启掘金创作之路。

前后端分离架构中，前后端对齐API接口是非常重要的一项工作。 后端接口生成API文档，首选Swagger，接入非常简单，代码入侵性低。 有几个问题需要解决：

  1. 前端要记录每个项目的SwaggerUI地址是一项很低效方式，如何统一管理（YApi）
  2. 统一管理后，API文档变更如何同步，手动同步对于后端来说额外增加了负担
  3. 如何按环境加载swagger组件（生成环境是不允许的）

Swagger + YApi 实践

对于问题2，可以通过YApi的Swagger自动同步连接到测试环境地址实现，剩下的只要程序员把代码推到测试环境就可以实现自动同步到YApi平台

image.png

对于问题3，代码如下，通过参数控制，开发环境开启，线上环境关闭

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.enable:true}")
    private Boolean enable;

    @Value("${spring.cloud.nacos.discovery.metadata.light.version}")
    private String serviceVersion;

    @Value("${spring.application.name}")
    private String serviceName;

    private static final String basePackage = "com.light.controller";

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enable)
                .apiInfo(apiInfo())
                .genericModelSubstitutes(Response.class)
                .forCodeGeneration(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(serviceName)
                .version(serviceVersion)
                .build();
    }
}

Swagger

Swagger是一套围绕OpenAPI规范构建的开源工具，可以帮助您设计、构建、编写文档和使用REST api。

OpenAPI规范(原Swagger规范)是REST API的API描述格式。一个OpenAPI文件允许你描述你的整个API。

swagger.io/

image.png

image.png

主要的Swagger工具包括:

  • Swagger Codegen:根据描述文件生成接口文档和代码
  • Swagger UI:提供了一个可视化的UI页面展示描述文件
  • Swagger Editor:编辑描述文件的编辑器
  • Swagger Inspector:可以对接口进行测试，会比SwaggerUI返回更多的信息
  • Swagger Hub:集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。

YApi

YApi是高效、易用、功能强大的api管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护API。 github.com/YMFE/yapi

image.png

功能特性：

  • 项目管理：提供基本的项目分组，项目管理，接口管理功能
  • 接口管理：友好的接口文档，基于websocket的多人协作接口编辑功能和类postman测试工具
  • MockServer：基于Mockjs，使用简单功能强大
  • 自动化测试：支持对Response断言
  • 数据导入：包括swagger、har、postman、json、命令行
  • 免费开源，内网部署
  • 支持插件和二次开发

其他工具

Postman

Postman是一款功能强大的网页调试与发送网页HTTP请求的工具。 www.getpostman.com/

Rap

RAP是一个可视化的接口管理工具。 thx.github.io/RAP/index_z…

EasyApi

EasyAPI是一个为您提供API管理、API测试、API监控、API文档的综合性API服务平台 www.easyapi.com

ShowDoc

一个非常适合IT团队的在线API文档、技术文档工具 www.showdoc.cc

Mock.js（生成随机数据）

生成随机数据，拦截Ajax请求 mockjs.com

EasyYApi

优雅的文档来自优雅的注释 easyyapi.com/index.html

avatar
文章
阅读
粉丝