【Swagger2 】spring-boot2.0.2 集成 Swagger2 打造在线接口文档_springfox swagger2.2-程序员宅基地

技术标签: Swagger  

一、Springfox 与 Swagger 简介

1.1 Springfox

Springfox 是一个开源的API Doc的框架, 它的前身是swagger-springmvc,能够完美的支持springmvc,可以将spring 接口方法自动转换为接口文档。 目前spring fox 正致力于对更多JSON API规范和标准的扩展和支持,例如:swagger,RAML和jsonapi。

1.2 Swagger

Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务,支持从整个API生命周期(从设计和文档到测试和部署)的开发。

swagger 是一个综合的开源项目,包含swagger-core、swagger-ui、swagger-codegen、swagger-editor等多个子项目。

swagger-core:Swagger Core是OpenAPI规范(以前称为Swagger规范)的Java实现。
swagger-ui:依据可视化文档,提供与API资源的可视化交互。
swagger-codegen:开源的代码生成器,根据Swagger定义的RESTful API可以自动建立服务端和客户端的连接。
swagger-editor:开源的api文档编辑器。
下图为swagger-ui 提供的文档可视化界面示例:

1.3 OpenApi、Swagger、Springfox的关系

Swagger Core 是 OpenApi 规范(以前称为Swagger规范)的Java 实现,而 Springfox 提供 Swagger 与 spring 的集成支持

 

二、spring boot 集成 swagger 2.0

2.1 导入项目相关依赖

<!--swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

 

2.2 进行swagger个性化配置、并用@EnableSwagger2开启Swagger支持

这里需要说明的是swagger虽然是一个非常直观易用的接口调试插件,但是有可能导致接口信息泄露的危险,所以建议在开发环境和测试环境开启,在生产环境关闭。这里一共给出三种Swagger开关切换的方法:

如下面代码所示,在配置文件中配置自定义的开关参数,并在创建Docket时候,在链式调用的enable()方法中传入;

在SwaggerConfig配置类上添加@Profile({"dev","test"})注解,指明在开发环境和测试环境下激活此配置类,打包或者部署时候使用spring.profiles.active指明环境即可;

在配置文件中配置自定义的开关参数,并在SwaggerConfig配置类上添加@ConditionalOnProperty(name = "swagger.enable", havingValue = "true"),指明配置类的生效条件

注:@ConditionalOnProperty 注解说明

@ConditionalOnProperty注解能够控制某个@configuration修饰的配置类是否生效。具体操作是通过name和havingValue属性来实现,name对应application.properties(yml)中的某个属性值,如果该值为空,则返回false;如果值不为空,则将该值与havingValue指定的值进行比较,如果一样则返回true;否则返回false。如果返回值为false,则该configuration不生效;为true则生效。
 

/**
 * @author : heibaiying
 * @description :  Swagger 配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /***
     * 一个标准的swagger注解
     */
    @ApiOperation(notes = "查询所有产品", value = "产品查询接口")
    @ApiImplicitParams(
            @ApiImplicitParam(name = "id", value = "产品编号", paramType = "path", defaultValue = "1")
    )
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "无效的请求"),
            @ApiResponse(code = 401, message = "未经过授权认证"),
            @ApiResponse(code = 403, message = "已经过授权认证,但是没有该资源对应的访问权限"),
            @ApiResponse(code = 404, message = "服务器找不到给定的资源,商品不存在"),
            @ApiResponse(code = 500, message = "服务器错误")
    })
    @GetMapping(value = "/product/{id}", produces = "application/json")
    public ResponseEntity<Product> getProduct(@PathVariable long id) {
        Product product = new Product(id, "product" + id, new Date());
        return ResponseEntity.ok(product);
    }


    /***
     * 如果用实体类接收参数,则用实体类对应的属性名称指定参数
     */
    @ApiOperation(notes = "保存产品", value = "产品保存接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "产品编号", paramType = "body", defaultValue = "1"),
            @ApiImplicitParam(name = "name", value = "产品名称", paramType = "body"),
            @ApiImplicitParam(name = "date", value = "产品生产日期", paramType = "body")
    }
    )
    @PostMapping(value = "/product")
    public ResponseEntity<Void> saveProduct(@RequestBody Product product) {
        System.out.println(product);
        return ResponseEntity.ok().build();
    }


    /***
     * 在配置类中指明了该接口不被扫描到,可以在配置类中使用正则指定某一类符合规则的接口不被扫描到
     */
    @ApiOperation(notes = "该接口会被忽略", value = "产品保存接口")
    @PostMapping(value = "/ignore")
    public ResponseEntity<Product> ignore() {
        return ResponseEntity.ok().build();
    }

    /**
     * 不加上任何swagger相关的注解也会被扫描到 如果不希望被扫描到,需要用 @ApiIgnore 修饰
     */
    @PostMapping(value = "/normal")
    public ResponseEntity<Void> normal() {
        return ResponseEntity.ok().build();
    }

    @ApiIgnore
    @PostMapping(value = "/apiIgnore")
    public ResponseEntity<Void> apiIgnore() {
        return ResponseEntity.ok().build();
    }
}

application.yml:

#swagger启用开关
swagger:
  enable: true

2.3 swagger注解的使用和说明

@Slf4j
@Api(value = "产品接口", description = "产品信息接口")
@RestController
public class ProductController {

    /***
     * 一个标准的swagger注解
     */
    @ApiOperation(notes = "查询所有产品", value = "产品查询接口")
    @ApiImplicitParams(
            @ApiImplicitParam(name = "id", value = "产品编号", paramType = "path", defaultValue = "1")
    )
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "无效的请求"),
            @ApiResponse(code = 401, message = "未经过授权认证"),
            @ApiResponse(code = 403, message = "已经过授权认证,但是没有该资源对应的访问权限"),
            @ApiResponse(code = 404, message = "服务器找不到给定的资源,商品不存在"),
            @ApiResponse(code = 500, message = "服务器错误")
    })
    @GetMapping(value = "/product/{id}", produces = "application/json")
    public ResponseEntity<Product> getProduct(@PathVariable long id) {
        Product product = new Product(id, "product" + id, new Date());
        return ResponseEntity.ok(product);
    }


    /***
     * 如果用实体类接收参数,则用实体类对应的属性名称指定参数
     */
    @ApiOperation(notes = "保存产品", value = "产品保存接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "产品编号", paramType = "body", defaultValue = "1"),
            @ApiImplicitParam(name = "name", value = "产品名称", paramType = "body"),
            @ApiImplicitParam(name = "date", value = "产品生产日期", paramType = "body")
    }
    )
    @PostMapping(value = "/product")
    public ResponseEntity<Void> saveProduct(@RequestBody Product product) {
        System.out.println(product);
        return ResponseEntity.ok().build();
    }


    /***
     * 在配置类中指明了该接口不被扫描到,可以在配置类中使用正则指定某一类符合规则的接口不被扫描到
     */
    @ApiOperation(notes = "该接口会被忽略", value = "产品保存接口")
    @PostMapping(value = "/ignore")
    public ResponseEntity<Product> ignore() {
        return ResponseEntity.ok().build();
    }

    /**
     * 不加上任何swagger相关的注解也会被扫描到 如果不希望被扫描到,需要用 @ApiIgnore 修饰
     */
    @PostMapping(value = "/normal")
    public ResponseEntity<Void> normal() {
        return ResponseEntity.ok().build();
    }

    @ApiIgnore
    @PostMapping(value = "/apiIgnore")
    public ResponseEntity<Void> apiIgnore() {
        return ResponseEntity.ok().build();
    }
}

swagger 为了最大程度防止对逻辑代码的侵入,基本都是依靠注解来完成文档描述。常用注解如下:
@Api:Api 用在类上,说明该类的作用;

@ApiOperation:用在方法上,说明方法的作用;

@ApiParam:用在参数上,说明参数的作用;

@ApiImplicitParams:用在方法上说明方法参数的作用;

@ApiImplicitParam:用在@ApiImplicitParams注解中,描述每个具体参数;

@ApiResponses:一组@ApiResponse的配置;

@ApiResponse:请求返回的配置;

@ResponseHeader:响应头的配置;

@ApiModel:描述一个Model的信息(一般用在post创建的时候,使用@RequestBody接收参数的场景);

@ApiModelProperty:描述model的属性。

@ApiIgnore:可以用于类、方法、属性,代表该方法、类、属性不被swagger的文档所管理。
 

2.4 swagger-ui 可视化接口文档

接口文档访问地址:http://localhost:8080/swagger-ui.html ,文档主界面如下:

2.5 利用swagger-ui进行接口测试

​点击对应接口的try it out按钮可以进行接口测试,此时可以输入对应的参数的值,然后点击下方的Execute按钮发送请求

 

 

转自:https://blog.csdn.net/m0_37809146/article/details/87160740

版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。
本文链接:https://blog.csdn.net/niuchenliang524/article/details/89149970

智能推荐

拓端tecdat|SAS用K-Means 聚类最优k值的选取和分析_sas k-m图-程序员宅基地

文章浏览阅读1.7k次。“聚类是将数据集分为几组的过程,其中包括相似的数据点”。聚类是一种无监督的机器学习,在您拥有未标记的数据时使用。_sas k-m图

LED的C语言应用程序_编写一个程序当光敏电阻检测到光线时点亮led当光线不足时熄灭led-程序员宅基地

文章浏览阅读3.1k次。在本文中,用C语言编写一个LED灯的应用程序,对文章《基于HDF的LED驱动程序开发》中开发的LED灯的驱动程序进行测试。_编写一个程序当光敏电阻检测到光线时点亮led当光线不足时熄灭led

微信小程序商城15天从零实战视频课程-商品分类_微信小程序商城 15天 csdn-程序员宅基地

文章浏览阅读954次。js代码//const app = getApp();Page({ /** * 页面的初始数据 */ data: { winWidth: 0, winHeight: 0, hidden: false, curNav: 1, curIndex: 0, navList: [ { id: 1, ..._微信小程序商城 15天 csdn

StringEscapeUtils - 用于Java/JS/HTML和XML字符互相转义和反转义_js stringescapeutils-程序员宅基地

文章浏览阅读4.9k次。 Apache工具包common-lang API提供了许多辅助工具,特别是字符串操作方法,基本数值方法,对象反射,并发,创建和序列化以及系统属性。此外,它还包含对java.util.Date的基本增强功能以​​及一系列专用于帮助构建方法的实用程序,例如hashCode,toString和equals。 StringEscapeUtils包含用于转义和转换Ja..._js stringescapeutils

JavaScript Base64编码和解码,实现URL参数传递。-程序员宅基地

文章浏览阅读138次。为什么需要对参数进行编码?相信有过开发的经验的广大程序员都知道,在Web中,若是直接在Url地址上传递参数值,若是中文,或者+等什么的就会出现乱码现象,若是数字或者英文的好象没有什么问题,简言之,传递过来的参数是需要进行编码的。在这里,也许有人会说,为什么不直接用Server.UrlDecode和Server.UrlEncode这两个来进行编码和解码的操作呢?的确,这两个服务器端对象很..._js baise 64 传url

C语言中用sizeof和strlen观察数组的变化2_c语言判断数组是否变化-程序员宅基地

文章浏览阅读938次,点赞27次,收藏19次。C语言中用sizeof和strlen观察数组的变化2_c语言判断数组是否变化

随便推点

python列表与元组、字典与集合的应用上机报告_def foo(ls, num): if num == 1: ls.append(0) elif n-程序员宅基地

文章浏览阅读4.5k次。一、实验目的和要求目的:(1)掌握累加求和问题的算法。(2)掌握根据整数的一些性质求解数字问题的算法。(3)掌握求解一元方程的迭代算法。(4)掌握序列的通用的操作方法。(5)掌握列表的专用操作方法。(6)理解元组与列表的区别。二、 实验数据记录、处理及结果分析① 写出程序的运行结果。② 筛选法求[2,n]范围内全部素数的基本思路是:在2~n中划去2的倍数(不包括2),再划去..._def foo(ls, num): if num == 1: ls.append(0) elif num == 2: foo(ls, 1) ls.app

青龙之腾讯自选股_青龙 腾讯自选股-程序员宅基地

文章浏览阅读8.4k次,点赞3次,收藏33次。1、青龙面板中选择添加任务2、拉取脚本扣扣裙获取脚本:9846983523、手动运行一次此任务,拉取脚本到青龙4、编辑一下拉下来的定时任务的定时,改成35 11,16 * * *5、准备工作5-1、下载【腾讯自选股】APP,可以直接appstore下载。5-2、关注腾讯自选股微信版|微证券 公众号腾讯自选股微信版|微证券6、打开抓包软件准备抓包。我下面直接用圈x举例了。圈x长按风车,弹出菜单中点击HTTP数据抓取按钮,将其打开共需要获取三个c_青龙 腾讯自选股

魅族16 android10,魅族16X 魔趣OS 安卓10 MagiskV20版 完美ROOT 纯净完美 原生极简 纯净推荐...-程序员宅基地

文章浏览阅读2k次。刷机包说明:刷机之前请实现解锁BootLoader,并刷入TWRP专用版本ROM也适用于小米红米以及魅族手机账户锁手机如果你是账户锁手机,刷入魔趣ROM后将不再有锁基于魔趣OS刷机包制作,纯净完美,无任何广告集成添加默认添加ROM底层,直接刷入,不再对底层限制,一步到位默认加入面具magisk V21最新版root权限,玩机达人必备支持TWRP_recovery直接刷入,第一次刷机请格式化data..._魅族16x魔趣

Json字符串Key转大写_jsonobject.parseobject key转换为大写-程序员宅基地

文章浏览阅读642次。public static JSONObject transToUpperObject(String json) { JSONObject JSONObject2 = new JSONObject(); JSONObject JSONObject1 = JSON.parseObject(json); for (String key : JSONObject1.keySet()){ Object object = JSONObject1._jsonobject.parseobject key转换为大写

基于翔云OCR云平台的人脸识别(2)_基于云平台人脸识别-程序员宅基地

文章浏览阅读370次。基于翔云OCR云平台的人脸识别(2)项目思路raspistill命令的相关参数说明-v:调试信息查看-w:图像宽度-h:图像高度-rot:图像旋转角度,只支持 0、90、180、270 度(这里说明一下,测试发现其他角度的输入都会被转换到这四个角度之上)-o:图像输出地址,例如image.jpg,如果文件名为“-”,将输出发送至标准输出设备-t:获取图像前等待时间,默认为5000,即5秒raspistill -o test.png -w 400 -h 400 -t 1000摄像头拍_基于云平台人脸识别

数据结构算法题/最大子矩阵(二维数组中和最大的连续子矩阵)_二维数组最大子序列矩阵题目-程序员宅基地

文章浏览阅读2.7k次。给定一个矩阵,都是整数,求出其中的最大子矩阵。可以将问题转换为求一维数组的最大子序列和的问题。具体见https://blog.csdn.net/fkyyly/article/details/83088247/** * 其实思想是控制新的子矩阵开始,按列相加变成一维数组,然后再求一维数组最大子序列的和, * 最后在多个最大子序列的和中返回最大的那个 * 然后对如上获取的不同子矩阵分别..._二维数组最大子序列矩阵题目

推荐文章

热门文章

相关标签