AI 助理
备案控制台
开发者社区 云计算 文章 正文

springfox-bridge：随心所欲地为非restful接口生成swagger api文档

2019-05-30 1503
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
简介： ### 一、引言     目前，利用swagger框架为restful接口编写API文档非常流行，在spring web项目中，利用springfox+swagger更是可以通过注解的方式直接进行API文档的生成，这样开发者在项目开发的同时就直接把文档准备好了，利用springfox的配置，可以在项目启动后直接浏览器访问查看API文档，同时还能

一、引言

    目前，利用swagger框架为restful接口编写API文档非常流行，在spring web项目中，利用springfox+swagger更是可以通过注解的方式直接进行API文档的生成，这样开发者在项目开发的同时就直接把文档准备好了，利用springfox的配置，可以在项目启动后直接浏览器访问查看API文档，同时还能在界面直接进行API的测试。springfox的使用本文不在此赘述了，现在引出一个问题: 非restful接口能否采用swagger生成接口文档？

    在项目中集成springfox-bridge可以快速的为非restful接口生成API文档，编写文档的方式跟springfox一样简单，在相关类或者接口上采用注解的方式定义文档信息即可。

    springfox-bridge相当于架设了一座与springfox之间的桥梁，通过动态生成配置了springfox注解的mvc接口并进行注册，形成对非restful接口生成swagger文档的能力。

项目github地址: https://github.com/double-bin/springfox-bridge

二、springfox-bridge特性说明

  1. 启动简单

    • 在springboot项目中，集成springfox-bridge-spring-boot-starter即可自动启动；
    • 在非springboot项目中，通过实现ApplicationContextAware接口，通过SpringfoxBridge.start(ApplicationContext context)方法,并配置@EnableSwagger2注解即可快速启动。

  2. 兼容性强

    • 与协议无关，不挑协议，无论你是使用dubbo、ServiceComb还是其它种种，只要项目本身启用了springmvc, 相应的接口注册了spring bean, 就能像使用springfox那样使用springfox-brige，用注解的方式为接口生成文档。
    • 更进一步的讲，只要满足上述条件的spring bean, 即使不是controller层的接口，也能使用springfox-bridge进行文档生成。

  3. 简单的注解

    • springfox-bridge提供了几个简单的注解供开发使用，注解的使用方式与springfox的类似，主要在类/接口、方法上进行文档的定义。

  4. 方便的分组

    • 采用@BridgeGroup注解可以方便的为项目的接口文档进行分组，而无需手动的配置Docket，springfox-bridge自动按照@BridgeGroup的注解值将文档进行分组归类。

  5. 不影响原有文档

    • springfox-bridge通过分组隔离，项目中原先使用springfox为restful接口生成的文档，不会受到springfox-bridge的影响

  6. 方法入参不限定请求体的数量

    • 原生springfox对restful请求生成文档，而restful只支持一个请求体入参（用@RequestBody注解标识）。springfox-bridge没有这个限制。

  7. 支持界面测试

    • 跟springfox生成文档可以通过界面直接调用一样，springfox-bridge同样支持

三、使用说明

使用springfox-bridge需要项目本身启用了springmvc框架， spring相关依赖版本在spring3.1以上

3.1 配置maven依赖

1）使用了springboot的项目：

        <dependency>
            <groupId>com.github.double-bin</groupId>
            <artifactId>springfox-bridge-spring-boot-starter</artifactId>
            <version>1.0.3</version>
        </dependency>

2) 非springboot项目：

        <dependency>
            <groupId>com.github.double-bin</groupId>
            <artifactId>springfox-bridge-core</artifactId>
            <version>1.0.3</version>
        </dependency>

3.2 启动配置

1）使用了springboot的项目

  • 配置了springfox-bridge-spring-boot-starter后，默认开启springfox-bridge。
  • 如果需要关闭，可以在application.properties文件(或yml文件)中配置springfox.bridge.enabled的值为false即可

2) 非springboot项目：

  • 可通过配置类实现ApplicationContextAware接口的setApplicationContext方法，方法实现中通过SpringfoxBridge.start()方法启动springfox-bridge, 配置类上通过@EnableSwagger2启动springfox基本功能， 可参考：
import org.springframework.beans.BeansException;
import org.springframework.context.ApplicationContext;
import org.springframework.context.ApplicationContextAware;
import org.springframework.context.annotation.Configuration;
import com.github.doublebin.springfox.bridge.core.SpringfoxBridge;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@EnableSwagger2
@Configuration
public class MyXXXConfiguration implements ApplicationContextAware {
    @Override
    public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
        SpringfoxBridge.start(applicationContext);

    }
}

3.3 使用示例

下面示例代码演示如何使用springfox-bridge的注解，如何定义的文档，如果设置分组等，展示结果请看3.4

1, 定义两个请求的model类：TestRquest1和TestRequest2

model类中可以使用springfox的原生注解：io.swagger.annotations.ApiModel和io.swagger.annotations.ApiModelProperty

package com.github.doublebin.springfox.bridge.demo.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
@ApiModel(value="TestRequest1", description = "测试请求体1")
public class TestRequest1 {

    @ApiModelProperty(value = "唯一id", required = true)
    private long uuid;

    @ApiModelProperty(value = "名字", required = true)
    private String name;
}

package com.github.doublebin.springfox.bridge.demo.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
@ApiModel(value="TestRequest2", description = "测试请求体2")
public class TestRequest2 {

    @ApiModelProperty(value = "名字", required = true)
    private String name;

    @ApiModelProperty(value = "描述", required = true)
    private String desc;
}
2, 定义三个service类，并标注@Service供spring扫描并注册bean。
package com.github.doublebin.springfox.bridge.demo.service;

import com.github.doublebin.springfox.bridge.demo.model.TestRequest1;
import com.github.doublebin.springfox.bridge.demo.model.TestRequest2;
import org.springframework.stereotype.Service;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeApi;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeGroup;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeModelProperty;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeOperation;

@Service
@BridgeApi(value = "TestService1 Apis", description = "测试服务1")
@BridgeGroup("test-group1")
public class TestService1 {

    @BridgeOperation(value = "测试查询1", notes = "测试查询方法1说明")
    public String testQuery(@BridgeModelProperty(value = "用户id", required = true) long id, @BridgeModelProperty(value = "请求2", required = false) TestRequest1 request){
        return "Test query success, id is " + id;
    }

    @BridgeOperation(value = "测试查询2", notes = "测试查询方法2说明")
    public String testQuery(@BridgeModelProperty(value = "用户id", required = true) long id){
        return "Test query success, id is " + id;
    }

    @BridgeOperation(value = "测试查询3", notes = "测试查询方法3说明")
    public String testQuery(){
        return "Test query success.";
    }

    @BridgeOperation(value = "测试查询4", notes = "测试查询方法4说明")
    public String testQuery(@BridgeModelProperty(value = "用户id", required = true) long id, @BridgeModelProperty(value = "请求2", required = false) TestRequest2 request){
        return "Test query success, id is " + id;
    }

}
package com.github.doublebin.springfox.bridge.demo.service;

import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeApi;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeGroup;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeModelProperty;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeOperation;
import com.github.doublebin.springfox.bridge.demo.model.TestRequest1;
import org.springframework.stereotype.Service;

@Service
@BridgeApi(value = "TestService2 Apis", description = "测试服务2")
@BridgeGroup("test-group2")
public class TestService2 {
    @BridgeOperation(value = "测试查询", notes = "测试查询方法说明")
    public String testQuery(@BridgeModelProperty(value = "用户id", required = true) long id, @BridgeModelProperty(value = "请求2", required = false) TestRequest1 request){
        return "Test query success, id is " + id;
    }
}

package com.github.doublebin.springfox.bridge.demo.service;

import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeApi;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeGroup;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeModelProperty;
import com.github.doublebin.springfox.bridge.core.builder.annotations.BridgeOperation;
import com.github.doublebin.springfox.bridge.demo.model.TestRequest1;
import org.springframework.stereotype.Service;

@Service
@BridgeApi(value = "TestService3 Apis", description = "测试服务3")
@BridgeGroup("test-group1")
public class TestService3 {
    @BridgeOperation(value = "测试查询", notes = "测试查询方法说明")
    public String testQuery(@BridgeModelProperty(value = "用户id", required = true) long id, @BridgeModelProperty(value = "请求2", required = false) TestRequest1 request){
        return "Test query success, id is " + id;
    }
}

 

    示例中定义了2个分组：test-group1 和 test-group2， 其中TestService1和TestService3归属于test-group1分组，TestService2归属于test-group2分组，其中TestService1中定义了多个不同的方法，在3.4节中会展示这些情况下的多个效果

3.4 示例效果展示

浏览器访问地址：http:${host}:${port}/${server.context-path}/swagger-ui.html

  1. 首先看下面两个分组的截图，其中test-group1:

test-group1.png

test-group2:

test-group2.png

说明:

  • 用spring-fox对某个类生成API文档，必须用在类上使用@BridgeApi注解，并在需要生成文档的方法上使用@BridgeOperation注解。
  • 如果要对某个类分组，可以在类上标识@BridgeGroup注解。前面示例中，通过@BridgeGroup注解定义了2个分组，将3个Service类进行了归类，在上面两图可以看到，通过下拉框切换分组后，将分别展示@BridgeGroup注解定义的不同分组的页面。当然@BridgeGroup如果不定义，springfox-bridge会生成一个名为defafult的分组，将没有显式定义@BridgeGroup注解的文档归类到default分组下。
  • swagger页面上类的tag采用类全名的方式展示，@BridgeApi注解的description值也会展示在界面上描述类的作用。
  • @BridgeOperation注解定义方法，springfox-bridge会在对应的类tag下生成对应的方法tag，由图可以看出，path路径的组成格式为：“/类全名/方法名/入参的类名首字母组合”。
  • 如果@BridgeOperation定义的方法没有入参，那么path路径中则没有“入参的类首字母组合”；如果两个同名方法入参的类名首字母组合相同，那么第二个及之后的同名方法的path路径会追加“/index数字”以区分不同的方法，index的排序以springfox-bridge内部对方法加载的顺序进行排序。
  • @BridgeOperation注解的value值标识该方法的简要说明，跟path在同一行展示。
  • @BridgeModelProperty注解可以对方法入参进行标识，用以对入参加以说明
  • 方法入参类型如果是一个model类，该model类可以用io.swagger包的原生注解@ApiModel（标识类）和@ApiModelProperty（标识字段）对model类进行说明，之所以用原生注解，是为了兼容原生springfox，不必重复定义注解。
  • 在swagger界面上可以看到，springfox-bridge对每个标识了@BridgeOperation的方法都动态生成一个post请求，并动态生成一个body请求体，方法的所有入参都作为新请求体的字段。

四、springfox-bridge注解说明

4.1 springfox-bridge自定义注解

注解 位置 主要字段 说明 对标原生注解
BridgeApi 类 description 对类进行说明 io.swagger.annotations.Api
BridgeGroup 类 value 标识分组 无
BridgeOperation 方法 value、notes value、notes分别标识方法概要和详细说明 io.swagger.annotations.ApiOperation
BridgeModelProperty 入参 value 标识入参说明 io.swagger.annotations.ApiModelProperty

4.2 兼容的springfox swagger原生注解

目前兼容入参的请求体的model用io.swagger包的原生注解@ApiModel、@ApiModelProperty ，后续会提供其它支持

五、展望

目前springfox-bridge的1.0.3版本已经发布到maven中央仓库，后续会更新支持更多的特性, 比如： 兼容更多的springfox swagger的原生注解、支持返回体说明、支持author自定义、支持入参类型全名展示等。项目源码见github： https://github.com/double-bin/springfox-bridge

关键词：
Restful API
API接口
API文档
Swagger api
API restful
游客g2wetgyzpqj3q
目录
相关文章
游客mass6jalwg5qm
|
6天前
|
XML JSON API
Understanding RESTful API and Web Services: Key Differences and Use Cases
在现代软件开发中，RESTful API和Web服务均用于实现系统间通信，但各有特点。RESTful API遵循REST原则，主要使用HTTP/HTTPS协议，数据格式多为JSON或XML，适用于无状态通信；而Web服务包括SOAP和REST，常用于基于网络的API，采用标准化方法如WSDL或OpenAPI。理解两者区别有助于选择适合应用需求的解决方案，构建高效、可扩展的应用程序。
游客mass6jalwg5qm
40 15
游客4rnkeq2m7q5hy
|
7天前
|
机器学习/深度学习 设计模式 API
Python 高级编程与实战：构建 RESTful API
本文深入探讨了使用 Python 构建 RESTful API 的方法，涵盖 Flask、Django REST Framework 和 FastAPI 三个主流框架。通过实战项目示例，详细讲解了如何处理 GET、POST 请求，并返回相应数据。学习这些技术将帮助你掌握构建高效、可靠的 Web API。
游客4rnkeq2m7q5hy
21 8
卓伊凡
|
1月前
|
JSON 前端开发 API
以项目登录接口为例-大前端之开发postman请求接口带token的请求测试-前端开发必学之一-如果要学会联调接口而不是纯写静态前端页面-这个是必学-本文以优雅草蜻蜓Q系统API为实践来演示我们如何带token请求接口-优雅草卓伊凡
以项目登录接口为例-大前端之开发postman请求接口带token的请求测试-前端开发必学之一-如果要学会联调接口而不是纯写静态前端页面-这个是必学-本文以优雅草蜻蜓Q系统API为实践来演示我们如何带token请求接口-优雅草卓伊凡
卓伊凡
64 5
以项目登录接口为例-大前端之开发postman请求接口带token的请求测试-前端开发必学之一-如果要学会联调接口而不是纯写静态前端页面-这个是必学-本文以优雅草蜻蜓Q系统API为实践来演示我们如何带token请求接口-优雅草卓伊凡
技术交流18179014480
|
8天前
|
机器学习/深度学习 JSON 算法
淘宝拍立淘按图搜索API接口系列的应用与数据解析
淘宝拍立淘按图搜索API接口是阿里巴巴旗下淘宝平台提供的一项基于图像识别技术的创新服务。以下是对该接口系列的应用与数据解析的详细分析
技术交流18179014480
34 4
winx_19970108018
|
27天前
|
监控 供应链 搜索推荐
亚马逊商品详情接口（亚马逊 API 系列）
亚马逊作为全球最大的电商平台之一，提供了丰富的商品资源。开发者和电商从业者可通过亚马逊商品详情接口获取商品的描述、价格、评论、排名等数据，对市场分析、竞品研究、价格监控及业务优化具有重要价值。接口基于MWS服务，支持HTTP/HTTPS协议，需注册并获得API权限。Python示例展示了如何使用mws库调用接口获取商品详情。应用场景包括价格监控、市场调研、智能选品、用户推荐和库存管理等，助力电商运营和决策。
winx_19970108018
95 23
winx_19970108018
|
1月前
|
JSON 数据挖掘 API
lazada商品详情接口 （lazada API系列）
Lazada 是东南亚知名电商平台，提供海量商品资源。通过其商品详情接口，开发者和商家可获取商品标题、价格、库存、描述、图片、用户评价等详细信息，助力市场竞争分析、商品优化及库存管理。接口采用 HTTP GET 请求，返回 JSON 格式的响应数据，支持 Python 等语言调用。应用场景包括竞品分析、价格趋势研究、用户评价分析及电商应用开发，为企业决策和用户体验提升提供有力支持。
winx_19970108018
89 21
winx_19970108018
|
25天前
|
JSON API 数据格式
eBay商品详情接口（ebay API系列）
eBay 商品详情接口是电商从业者、开发者和数据分析师获取商品详细信息的重要工具，涵盖标题、价格、库存、卖家信息等。使用前需在 eBay 开发者平台注册并获取 API 凭证，通过 HTTP GET 请求调用接口，返回 JSON 格式数据。Python 示例代码展示了如何发送请求并解析响应，确保合法合规使用数据。
winx_19970108018
60 12
winx_19970108018
|
24天前
|
JSON API 数据格式
阿里巴巴商品详情接口（阿里巴巴 API 系列）
在电商开发中，获取阿里巴巴商品详情信息对数据分析、竞品研究等至关重要。通过调用其商品详情接口，开发者可获取标题、价格、图片、描述等数据，满足多种业务需求。接口采用HTTPS协议，支持GET/POST请求，返回JSON格式数据。示例代码展示了如何使用Python的requests库进行接口请求，需传递商品ID和访问令牌。实际应用时，请依据官方文档调整参数并确保安全性。
winx_19970108018
58 10
benson1131
|
24天前
|
存储 机器学习/深度学习 人工智能
如何使用非结构化 API 高效处理文档
手动处理非结构化文档面临格式不一致、数据噪声多和信息检索困难等挑战，导致低效率和合规风险。Unstructured API 通过自动化文档处理，利用AI技术简化分类、归类和异常检测，节省时间和提高准确性。Supametas.AI 作为领先平台，支持多种文件类型（如文本、图片、视频），适用于各行各业，可与Salesforce、Zendesk等工具无缝集成，确保数据流动顺畅并提升工作效率。其强大的功能包括数据摄取、处理技术、检索增强生成、灵活性、可扩展性和集成能力，帮助企业和小公司高效处理大量非结构化数据，实现业务增长和优化工作流程。
benson1131
78 4
WBKJ_Noah18870292986
|
7天前
|
存储 缓存 监控
如何高效爬取天猫商品数据？官方API与非官方接口全解析
本文介绍两种天猫商品数据爬取方案：官方API和非官方接口。官方API合法合规，适合企业长期使用，需申请企业资质；非官方接口适合快速验证需求，但需应对反爬机制。详细内容涵盖开发步骤、Python实现示例、反爬策略、数据解析与存储、注意事项及扩展应用场景。推荐工具链包括Playwright、aiohttp、lxml等。如需进一步帮助，请联系作者。
WBKJ_Noah18870292986
37 0

热门文章

最新文章

  • 1
    深度评测 | 仅用3分钟，百炼调用满血版 Deepseek-r1 API，百万Token免费用，简直不要太爽。
  • 2
    👉「免费满血DeepSeek实战-联网搜索×Prompt秘籍｜暨6平台横评」
  • 3
    【重磅发布】 免费领取阿里云百炼AI大模型100万Tokens教程出炉，API接口实战操作，DeepSeek-R1满血版即刻体验!
  • 4
    获取百炼API-KEY
  • 5
    阿里云微服务引擎 MSE 及 云原生 API 网关 2025 年 2 月产品动态
  • 6
    一文轻松拿下DeepSeek满血版的Api接口接入
  • 7
    DeepClaude：结合 DeepSeek R1 和 Claude AI 各自优势开发的 AI 应用平台，支持 API 调用和零延迟的即时响应
  • 8
    Temu商品列表数据接口（Temu API系列）
  • 9
    AI 程序员的4个分身 | 代码生成专家+注释精灵+API集成助手+智能调试伙伴
  • 10
    企业级API集成方案：基于阿里云函数计算调用DeepSeek全解析
  • 1
    Understanding RESTful API and Web Services: Key Differences and Use Cases
    40
  • 2
    Python 高级编程与实战：构建 RESTful API
    21
  • 3
    PHP 中基于 Casbin 做 RBAC + RESTful 权限控制
    66
  • 4
    深入浅出Node.js：从零开始构建RESTful API
    78
  • 5
    深入理解RESTful API设计原则与实践
    108
  • 6
    构建高效RESTful API的后端实践指南####
    62
  • 7
    深入理解RESTful API设计原则
    57
  • 8
    深入理解RESTful API设计原则
    71
  • 9
    构建高效RESTful API：后端开发的艺术与实践####
    54
  • 10
    深入浅出：构建高效RESTful API的最佳实践
    71

    • 相关电子书

    更多
  • Spring Boot2.0实战Redis分布式缓存
  • CUDA MATH API
  • API PLAYBOOK

    • 相关实验场景

    更多
  • 基于Assistant Api的旅游助手
  • 快速体验智能体API应用
    • 下一篇
    阿里云百炼已上线超强推理开源模型QwQ-32B，尺寸更小，性能比肩DeepSeek满血版