【小家Spring】借助Springfox整合SpringBoot和Swagger(API接口神器)

简介: 【小家Spring】借助Springfox整合SpringBoot和Swagger(API接口神器)

背景


随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。


前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架。


没有API文档工具之前,大家都是手写API文档的,在什么地方书写的都有,有在confluence上写的,有在对应的项目目录下readme.md上写的,每个公司都有每个公司的玩法,无所谓好坏(其实相比于Swagger,都不好)。


书写API文档的工具有很多,但是能称之为“框架”的,估计也只有swagger了。


swagger的生态使用图



image.png



Springfox解释


swagger是一个流行的API开发框架,这个框架以“开放API声明”(OpenAPI Specification,OAS)为基础,对整个API的开发周期都提供了相应的解决方案,是一个非常庞大的项目(包括设计、编码和测试,几乎支持所有语言)。


于Spring的流行,Marty Pitt编写了一个基于Spring的组件swagger-springmvc,用于将swagger集成到springmvc中来。而springfox则是从这个组件发展而来,同时springfox也是一个新的项目,本文仍然是使用其中的一个组件springfox-swagger2。


pringfox-swagger2依然是依赖OSA规范文档,也就是一个描述API的json文件,而这个组件的功能就是帮助我们自动生成这个json文件,我们会用到的另外一个组件springfox-swagger-ui就是将这个json文件解析出来,用一种更友好的方式呈现出来。


Swagger是一款 RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful风格的Web服务,加上 swagger-ui,可以有很好的呈现。


与SpringBoot集成的步骤


第一步:导入依赖(本文采用SpringBoot2+springfox2.9.2版本)


    <-- boot相关依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    <!--整合swagger-->
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>


第二步:书写SwaggerConfig配置文件


/**
 * @author fangshixiang
 * @description
 * @date 2018-11-14 10:48
 */
@EnableSwagger2 //开启springfox的Swagger2
@Configuration
//@Profile("dev") //只有在测试环境才开启Swagger
public class SwaggerConfig {
    //是否开启swagger,正式环境一般是需要关闭的,可根据springboot的多环境配置进行设置
    //若配置类上写了使用了@Profile 也可以达到类似效果 二选一 此处默认值为true
    @Value(value = "${swagger.enable:true}")
    private Boolean swaggerEnable;
    /**
     * 创建一个Docket 并且注册到Spring容器里即可完成配置
     *
     * @return Docket
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                //是否开启
                .enable(swaggerEnable)
                //设置API描述信息
                .apiInfo(apiInfo())
                .select()
                //扫描的的包 一般定位到controller那即可(若有接口层,此处报名需要注意)
                .apis(RequestHandlerSelectors.basePackage("com.fsx.run2.controller"))
                // 指定路径处理:PathSelectors.any()代表所有的路径
                // 也可以指定某些接口不要对外暴露 这里定义一些规则就行 如正则表达式
                .paths(PathSelectors.any())
                .build()
                //base,最终调用接口后会和paths拼接在一起
                .pathMapping("/");
    }
    //设置API信息 一些简单的描述信息而已
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API Document for 自定义服务名")
                .description("API描述信息")
                .contact(new Contact("Fangshixiang", "https://www.baidu.com", "shixiangfang@aliyun.com"))
                .version("1.0.0")
                .build();
    }
}


第三步:书写测试的Controller类


@RestController
@RequestMapping("/demo")
@Api(tags = "Demo API接口文档")
public class DemoController {
    @ApiOperation("根据id获取一条记录")
    @GetMapping("/{id}")
    Object getById(@PathVariable Integer id) {
        return id;
    }
}


最后,启动项目,访问:http://localhost:8080/swagger-ui.html


image.png


这样,API文档就自动生成了,我们只需要把这个连接发给前端,前端就能对API接口的相关数据结构一目了然,体验非常好


image.png


强烈建议在生产环境关闭 swagger,避免不必要的漏洞暴露!


Springfox简单原理


在前言中,我们知道,我们的第一个任务就是生成一个满足OSA规范的json文件(当然,创建一个spring的项目就不说了)。对于这个任务,springfox为我们提供了一个Docket(摘要的意思)类,我们需要把它做成一个Bean注入到spring中,显然,我们需要一个配置文件,并通过一种方式(显然它会是一个注解)告诉程序,这是一个Swagger配置文件。


这就是Springfox的强大之处,他启动时候回去扫描包下的controller,然后组装成json,然后放在内存里。最后提供UI界面直接访问即可,非常方便。


Swagger其余小组件介绍



swagger-editor(需要单独安装在操作系统上,使用较少)


就是一个在线编辑文档说明文件(swagger.json或swagger.yaml文件)的工具,以方便生态中的其他小工具(swagger-ui)等使用。

左边编辑,右边立马就显示出编辑内容来。


image.png


swagger-codegen


代码生成器,脚手架。可以根据swagger.json或者swagger.yml文件生成指定的计算机语言指定框架的代码。 有一定用处,Java系用的挺多。

对于从来不喜欢自动生成代码的我,觉得鸡肋


swagger-validator


这个小工具是用来校验生成的文档说明文件是否符合语法规定的。用法非常简单,只需url地址栏,根路径下加上一个参数url,参数内容是放swagger说明文件的地址。即可校验。


最后


Swagger在分布式环境下,可以结合网关聚合API文档,具体参考:

利用swagger2聚合API文档

聚合API文档在开放过程中,可以大大提高效率,值得推荐



相关文章
|
1天前
|
JSON API 数据格式
阿里巴巴商品详情接口(阿里巴巴 API 系列)
在电商开发中,获取阿里巴巴商品详情信息对数据分析、竞品研究等至关重要。通过调用其商品详情接口,开发者可获取标题、价格、图片、描述等数据,满足多种业务需求。接口采用HTTPS协议,支持GET/POST请求,返回JSON格式数据。示例代码展示了如何使用Python的requests库进行接口请求,需传递商品ID和访问令牌。实际应用时,请依据官方文档调整参数并确保安全性。
27 10
|
2天前
|
JSON API 数据格式
eBay商品详情接口(ebay API系列)
eBay 商品详情接口是电商从业者、开发者和数据分析师获取商品详细信息的重要工具,涵盖标题、价格、库存、卖家信息等。使用前需在 eBay 开发者平台注册并获取 API 凭证,通过 HTTP GET 请求调用接口,返回 JSON 格式数据。Python 示例代码展示了如何发送请求并解析响应,确保合法合规使用数据。
32 12
|
4天前
|
监控 供应链 搜索推荐
亚马逊商品详情接口(亚马逊 API 系列)
亚马逊作为全球最大的电商平台之一,提供了丰富的商品资源。开发者和电商从业者可通过亚马逊商品详情接口获取商品的描述、价格、评论、排名等数据,对市场分析、竞品研究、价格监控及业务优化具有重要价值。接口基于MWS服务,支持HTTP/HTTPS协议,需注册并获得API权限。Python示例展示了如何使用mws库调用接口获取商品详情。应用场景包括价格监控、市场调研、智能选品、用户推荐和库存管理等,助力电商运营和决策。
51 23
|
5天前
|
JSON 前端开发 API
以项目登录接口为例-大前端之开发postman请求接口带token的请求测试-前端开发必学之一-如果要学会联调接口而不是纯写静态前端页面-这个是必学-本文以优雅草蜻蜓Q系统API为实践来演示我们如何带token请求接口-优雅草卓伊凡
以项目登录接口为例-大前端之开发postman请求接口带token的请求测试-前端开发必学之一-如果要学会联调接口而不是纯写静态前端页面-这个是必学-本文以优雅草蜻蜓Q系统API为实践来演示我们如何带token请求接口-优雅草卓伊凡
29 5
以项目登录接口为例-大前端之开发postman请求接口带token的请求测试-前端开发必学之一-如果要学会联调接口而不是纯写静态前端页面-这个是必学-本文以优雅草蜻蜓Q系统API为实践来演示我们如何带token请求接口-优雅草卓伊凡
|
5天前
|
JSON 数据挖掘 API
lazada商品详情接口 (lazada API系列)
Lazada 是东南亚知名电商平台,提供海量商品资源。通过其商品详情接口,开发者和商家可获取商品标题、价格、库存、描述、图片、用户评价等详细信息,助力市场竞争分析、商品优化及库存管理。接口采用 HTTP GET 请求,返回 JSON 格式的响应数据,支持 Python 等语言调用。应用场景包括竞品分析、价格趋势研究、用户评价分析及电商应用开发,为企业决策和用户体验提升提供有力支持。
52 21
|
6天前
|
数据采集 JSON 监控
速卖通商品列表接口(以 AliExpress Affiliate 商品查询 API 为例)
以下是使用 Python 调用速卖通商品列表接口(以 AliExpress Affiliate 商品查询 API 为例)的代码示例。该示例包含准备基础参数、生成签名、发送请求和处理响应等关键步骤,并附有详细注释说明。代码展示了如何通过公共参数和业务参数构建请求,使用 HMAC-SHA256 加密生成签名,确保请求的安全性。最后,解析 JSON 响应并输出商品信息。此接口适用于商品监控、数据采集与分析及商品推荐等场景。注意需通过 OAuth2.0 获取 `access_token`,并根据官方文档调整参数和频率限制。
|
6天前
|
JSON 监控 API
速卖通商品列表接口(速卖通API系列)
速卖通提供商品列表API,开发者可通过关键词、类目、价格范围等条件获取商品标题、价格、销量等基本信息。使用前需注册开发者账号、创建应用并授权获取access_token。Python示例代码展示了如何调用接口,返回JSON格式数据,包含商品列表、总数、页码等信息。应用场景包括商品监控、数据分析和个性化推荐。注意API会更新,请参考官方文档。
|
7天前
|
存储 搜索推荐 API
淘宝拍立淘按图搜索API接口系列概述
淘宝拍立淘按图搜索API接口允许用户通过上传图片或拍摄实物来搜索相似或相同的商品。这一功能主要依赖于图像识别技术,系统会对上传的图片进行分析和处理,提取出商品的特征信息,并在淘宝的商品数据库中进行匹配搜索,最终返回与上传图片相似或相同的商品列表。
|
7天前
|
API PHP 开发者
速卖通商品详情接口(速卖通API系列)
速卖通(AliExpress)是阿里巴巴旗下的跨境电商平台,提供丰富的商品数据。通过速卖通开放平台(AliExpress Open API),开发者可获取商品详情、订单管理等数据。主要功能包括商品搜索、商品详情、订单管理和数据报告。商品详情接口aliexpress.affiliate.productdetail.get用于获取商品标题、价格、图片等详细信息。开发者需注册账号并创建应用以获取App Key和App Secret,使用PHP等语言调用API。该接口支持多种请求参数和返回字段,方便集成到各类电商应用中。
|
7天前
|
缓存 Java 应用服务中间件
java语言后台管理若依框架-登录提示404-接口异常-系统接口404异常如何处理-登录验证码不显示prod-api/captchaImage 404 (Not Found) 如何处理-解决方案优雅草卓伊凡
java语言后台管理若依框架-登录提示404-接口异常-系统接口404异常如何处理-登录验证码不显示prod-api/captchaImage 404 (Not Found) 如何处理-解决方案优雅草卓伊凡
35 5