Swagger2由入门到实战

一、为什么使用Swagger2
当下很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的工程师完成。在这种开发模式下，维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的，相信大家也都知道这种方式很难保证文档的及时性，这种文档久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式，下面我们就来了解一下它的优点：

1、代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。

2、跨语言性，支持 40 多种语言。

3、Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。

4、还可以将文档规范导入相关的工具（例如 Postman、SoapUI）, 这些工具将会为我们自动地创建自动化测试。

二.配置使用Swagger2

1、在pom.xml加入swagger2相关依赖

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><groupId>com.xncoding</groupId><artifactId>springboot-swagger2</artifactId><version>1.0.0-SNAPSHOT</version><packaging>jar</packaging><name>springboot-swagger2</name><description>集成Swagger2</description><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.0.4.RELEASE</version></parent><properties><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding><java.version>1.8</java.version></properties><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId><exclusions><exclusion><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-tomcat</artifactId></exclusion></exclusions></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-jetty</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope><exclusions><exclusion><groupId>com.vaadin.external.google</groupId><artifactId>android-json</artifactId></exclusion></exclusions></dependency><dependency><groupId>commons-io</groupId><artifactId>commons-io</artifactId><version>2.5</version></dependency><dependency><groupId>org.apache.commons</groupId><artifactId>commons-lang3</artifactId><version>3.7</version></dependency><dependency><groupId>commons-codec</groupId><artifactId>commons-codec</artifactId><version>1.11</version></dependency><!-- swagger2 集成--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.8.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.8.0</version></dependency><dependency><groupId>org.pegdown</groupId><artifactId>pegdown</artifactId><version>1.6.0</version><scope>test</scope></dependency><dependency><groupId>io.github.swagger2markup</groupId><artifactId>swagger2markup</artifactId><version>1.3.1</version><scope>test</scope></dependency></dependencies><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><configuration><fork>true</fork><addResources>true</addResources></configuration></plugin></plugins><!--将mapper文件打包进去--><resources><resource><!--指定根目录 到源文件夹 一般如下--><directory>src/main/java</directory><includes><include>**/*.yml</include><include>**/*.yaml</include><include>**/*.xml</include><include>**/*.properties</include></includes><filtering>false</filtering></resource><resource> <!--指定根目录 到源文件夹 一般如下--><directory>src/main/resources</directory><includes><include>**/*.yml</include><include>**/*.yaml</include><include>**/*.xml</include><include>**/*.properties</include></includes><filtering>false</filtering></resource></resources></build></project>

2.新建Swagger2的配置类：

/*** Swagger2的Java配置类** @author XiongNeng* @version 1.0* @since 2018/1/7*/
@Configuration
@EnableSwagger2
public class Swagger2Config {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).produces(Sets.newHashSet("application/json")).consumes(Sets.newHashSet("application/json")).protocols(Sets.newHashSet("http", "https")).apiInfo(apiInfo()).forCodeGeneration(true).select()// 指定controller存放的目录路径.apis(RequestHandlerSelectors.basePackage("com.cjlcoding.jwt"))
//                .paths(PathSelectors.ant("/api/v1/*")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder()// 文档标题.title("系统API服务")// 文档描述.description("系统API接口文档")// .termsOfServiceUrl("https://github.com").version("v1")// .license("MIT 协议")// .licenseUrl("http://www.opensource.org/licenses/MIT")// .contact(new Contact("chenjl","https://github.com/yidao620c","453252@gmail.com")).build();}
}

三、Swagger2注解详解
关于请求方式和请求路径，swagger默认为类上的请求方式添加解释说明，自动生成显示对应方法的请求方式和访问方法的相对路径。

1、@Api ：请求类的说明

@Api：放在请求的类上，与 @Controller 并列，说明类的作用，如人行衍生类，信天翁类，公安部类等。
tags=“说明该类的作用”
value=“该参数没什么意义，所以不需要配置”
description=“类功能性描述”(过时)

注：如果没指定tags,tags默认值与类名保持一致，description默认与类名保持一致

举例 @Api：

@Api(tags = {"生成随机数相关模块"},value = "我不显示",description = "生成随机数的类")
@RestController
@RequestMapping("/dynamistic/grow")
public class Practice2 {}

2、@ApiOperation：方法的说明

@ApiOperation：“用在请求的方法上，说明方法的作用”
value=“说明方法的作用”
notes=“方法的备注说明”

举例 @ApiOperation：

@ApiOperation(value = "生成bitNum位radix进制随机数,值得类型valueType", notes = "用于生成二维码的数据源")
@GetMapping("/random")
public GrowNum growRandomNum(@RequestParam int bitNum,@RequestParam String radix,@RequestParam String valueType) {return new GrowNum();
}

3、@ApiImplicitParams、@ApiImplicitParam：方法参数的说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）–> 请求参数的获取：@PathVariable
· body（请求体）–> @RequestBody User user
· form（普通表单提交）
dataType：参数类型，默认String，其它值dataType=“int”
defaultValue：参数的默认值

@ApiImplicitParams、@ApiImplicitParam举例：

@ApiImplicitParams({@ApiImplicitParam(name = "bitNum", value = "位", required = true, paramType = "Integer"),@ApiImplicitParam(name = "radix", value = "进制", required = true, paramType = "String"),@ApiImplicitParam(name = "valueType", value = "随机数类型", required = false, paramType = "String")})@GetMapping("/random")public GrowNum growRandomNum(@RequestParam int bitNum,@RequestParam String radix,@RequestParam String valueType) {return new GrowNum();}

4、@ApiResponses、@ApiResponse：方法返回值的说明

@ApiResponses：方法返回对象的说明
@ApiResponse：每个参数的说明
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类

举例@ApiResponses、@ApiResponse：

@ApiResponses(value = {@ApiResponse(code = 200, message = "请求已完成"),@ApiResponse(code = 201,message = "资源成功被创建"),@ApiResponse(code = 400,message = "请求中有语法问题,或不能满足请求"),@ApiResponse(code = 401,message = "未授权客户机访问数据"),@ApiResponse(code = 403,message = "服务器接受请求，但是拒绝处理"),@ApiResponse(code = 404,message = "服务器找不到给定的资源;文档不存在"),@ApiResponse(code = 500,message = "服务器出现异常")
})
@RestController
@RequestMapping("/dynamistic/grow")
public class Practice2 {}

5、@ApiModel：用于JavaBean上面，表示一个JavaBean
@ApiModel：用于JavaBean的类上面，表示此 JavaBean 整体的信息
（这种一般用在post创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候）

6. @ApiModelProperty：用在JavaBean的属性上面，说明属性的含义

举例 @ApiModel和 @ApiModelProperty：

@ApiModel("生成随机数的相关属性model")
@Component
public class GrowNum {@ApiModelProperty("随机数的位数")private Integer bitNum;@ApiModelProperty("进制数")private String radix;@ApiModelProperty("随机数值的类型")private String valueType;}

启动项目页面访问路径:http://localhost:8080/swagger-ui.html

完整代码已经上传到gitee上，路径：https://gitee.com/maganminga/springboot-buckets/tree/master/springboot-swagger2

Swagger2由入门到实战相关推荐

《Go语言从入门到实战》学习笔记（1）——Go语言学习路线图、简介
非常有幸在<极客时间>上看到<Go语言从入门到实战>这门课程,本课程的作者给出了较为详细的学习路线图,具体如下: 学习路线图学习目的个人学习的目的主要是了解Go语言的基本 ...
PyTorch深度学习入门与实战（案例视频精讲）
作者:孙玉林,余本国著出版社:中国水利水电出版社品牌:智博尚书出版时间:2020-07-01 PyTorch深度学习入门与实战(案例视频精讲)
7-Python3从入门到实战—基础之数据类型（字典-Dictionary）
Python从入门到实战系列--目录字典的定义字典是另一种可变容器模型,且可存储任意类型对象:使用键-值(key-value)存储,具有极快的查找速度: 字典的每个键值(key=>value ...
《Android 开发入门与实战（第二版）》——6.6节配置改变
本节书摘来自异步社区<Android 开发入门与实战(第二版)>一书中的第6章,第6.6节配置改变,作者eoe移动开发者社区组编 , 姚尚朗 , 靳岩,更多章节内容可以访问云栖社区&qu ...
【前端开发】HTML入门与实战
[什么是HTML]: HTML: 超文本标记语言,标准通用标记语言下的一个应用. "超文本"就是指页面内可以包含图片.链接,甚至音乐.程序等非文字元素. HTML 是用来描述网页的 ...
5-Python3从入门到实战—基础之数据类型（列表-List）
Python从入门到实战系列--目录列表定义 list:列表(list)是Python内置的一种数据类型,list是一种有序的集合,索引从0开始,可以进行截取.组合等: //创建列表list1 = ...
《树莓派Python编程入门与实战》——3.5　关于Python交互式shell
本节书摘来异步社区<树莓派Python编程入门与实战>一书中的第3章,第3.5节,作者:[美]Richard Blum,更多章节内容可以访问云栖社区"异步社区"公众号查 ...
js模板字符串自定义类名_【Vue.js 入门到实战教程】07Vue 组件注册 | 基本使用和组件嵌套...
来源 | https://xueyuanjun.com/post/21929除了前面介绍的基本语法之外,Vue.js 还支持通过组件构建复杂的功能模块,组件可以称得上是 Vue.js 的灵魂,是 Vu ...
《树莓派Python编程入门与实战（第2版）》——3.9　小结
本节书摘来自异步社区<树莓派Python编程入门与实战(第2版)>一书中的第3章,第3.9节,作者[美] Richard Blum Christine Bresnahan,陈晓明马立新 ...
《Angular4从入门到实战》学习笔记
<Angular4从入门到实战>学习笔记腾讯课堂:米斯特吴视频讲座二〇一九年二月十三日星期三14时14分 What Is Angular?(简介) 前端最流行的主流JavaScrip ...

Swagger2由入门到实战

Swagger2由入门到实战相关推荐

最新文章

热门文章