文章目录
一. 概述
1. 概念
swagger是什么？
Swagger是一种用于REST API的开源框架，它允许开发人员设计、构建、文档化和测试API。 Swagger提供了一套工具，帮助开发人员在开发API时自动生成文档，并与API的客户端代码保持同步。 Swagger还支持多种编程语言和框架，并包含许多功能，例如API验证、授权、版本
为什么要用swagger？
- 配置简单容易上手： 例如想要在SpringBoot工程中使用Swagger，不用编写任何繁琐的xml配置，只需要将指定好的依赖导入pom.xml中即可，并且再根据一个简单的Swagger配置类即可使用。
- 界面友好通俗易懂： Swagger 通过内置 html 解析器的方式来实现将 RESTFUL API数据显示在界面上供开发者查看，界面样式既简洁又美观，开发者可以很直观地看到自己所编写的 RESTFUL API 的请求方式、请求参数、返回格式以及所属业务组。
- 快速测试便于交互：例如在开发SpringBoot项目的时候，在测试接口时需要用到浏览器（默认只支持GET请求）或者postman，前者测试能力有限，后者又太繁琐，每次都需要切换不同的请求和URL地址，使得开发效率的降低，而使用了Swagger之后，只需要在响应的类和方法上使用注解进行说明，Swagger就会生成一份完整的接口文档和注释说明。
2. swagger优点
- 格式导出灵活 : 支持 Json 和 yml 来编写 API 文档，并且支持导出为 json、yml、markdown 等格式。
- 跨语言支持性 : 只针对 API，而不针对特定语言的 API，很多自动生成 API 的工具基本都是只针对特定的 API。
- 界面清晰易懂 : 界面清晰，无论是 Editor 的实时展示还是 Swagg-UI 界面的展示都十分人性化，简单明了。
3. swagger缺点
- 无法自定义格式 : Swagger-UI 封装好了一套 Html 模板，任何 RESTFUL API 的展示形式只能遵循其格式，不能灵活修改。
- 官方文档不全面 : Swagger 官方针对不同的模块提供了不同的介绍文档，但是缺乏系统的介绍，不利于入门学习。
二. SpringBoot集成Swagger
1. 整合过程
- 导入相关依赖
<!-- swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
- 编写swagger配置类
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
// SwaggerUI界面配置
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot接口文档")
.description("接口文档")
.contact(new Contact("Bear","http://www.yuque.com/bearpessimist","1942496795@qq.com"))
.version("1.0")
.build();
}
}
- docket方法解释：
- 首先在配置类上标注了 @Configuration表示这是一个配置类，如同原生Spring中的标签，@EnableSwagger2注解表示开启Swagger功能。
- 在docket方法上标注了@Bean注解，表示将此方法注入到bean工厂装配属性，相等于xml配置中的标签。然后new了一个Docket对象，并构造了一个DocumentationType类型的参数，该参数表示文档的类型，SWAGGER_2表示使用的Swagger版本是2.x系列。
- apiInfo中构造的是第二个方法，配置的是API描述信息，select()方法则是一个连接方法，通过构造器继续构造其它的功能。
- apis() 方法中通过RequestHandlerSelectors.basePackage() 来指定扫描包中的controller接口并生成响应的测试api，如果不配置此项则不会生成测试的api
- paths()方法中也是通过PathSelectors.any()方法，表示扫描接口中所有的请求路径。
- build()方法表示内容构建完毕，返回结果数据。
- apiInfo方法解释：
- ApiInfo类型代表SwaggerUI界面的基本信息，内部通过ApiInfoBuilder 建造者模式来返回一个实例
- title()方法：SwaggerUI界面的主标题
- description()方法：文档界面的描述信息
- contact()方法：作者的联系方式，通过new 一个Contact对象来构造作者名称，网站地址和邮箱
- version()方法：接口文档的版本。
- 测试
package com.swagger.controller;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserController {
@GetMapping("/hello")
public String hello() {
return "Hello,World";
}
}
然后就可以在界面上进行参数的设置来对接口进行测试
三. Swagger常用的注解说明
1. @Api 注解
标记在一个类上并作为Swagger中的资源。其主要作用就是给接口的类定义一些相关的说明，允许自定义类的描述和分组等功能
源码分析
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface Api {
// 标记接口类的说明
String value() default "";
// 标记接口类的说明，可分组显示
String[] tags() default "";
// 设置接口类请求头的输出类型
String produces() default "";
// 设置接口类请求头的输入类型
String consumes() default "";
// 添加支持的网络请求协议
String protocols() default "";
// 设置授权信息
Authorization[] authorizations() default @Authorization(value = "");
// 隐藏接口类的Api文档
boolean hidden() default false;
}
value属性
@RestController
@Api(value = "用户控制器")
public class UserController {}
该属性用于指定目标类的描述说明，来通过注释解释该类的作用。本质上就相当于一个注解说明
tag属性
tags()属性是一个数组类型，它可以将接口类注明信息并且分成多个组显示。它可以作用到ui界面
@RestController
@Api(tags = {"user1","user2"})
public class UserController {}
这样标注的结果就是分别有一个名为user1，user2的组，并且文档内容都一致。如下图
produces()&consumes()属性
produces指的是该接口类的返回值类型，consumes则是指处理请求提交内容的类型
@RestController
@Api(tags = {"用户控制器"},produces = "application/json",consumes = "application/json")
public class UserController {}
protocols&hidden 属性
protocols参数是指定接口类中使用的传输协议，例如http、https，而hidden属性则会隐藏接口类的测试api
@RestController
@Api(protocols = "http",hidden = true)
public class UserController {}
需要注意的是，即使设置了hidden为true，打开ui界面时测试接口也没有被隐藏，不知道是不是版本的bug，反正这些功能都是可选的。可有可无
Authorization 属性
指定授权的参数，需要配合权限认证功能。
2. @ApiOperation注解
该注解用于描述每个接口的作用，目的就是能够方便的知道每个接口分别有什么功能，达到见名知意的目的，ApiOperation可以作用在类和方法上，但通常都注释在方法上表名每个接口的释义。
注解源码
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiOperation {
// 接口描述
String value();
// 接口发布说明
String notes() default "";
// 接口描述，带分组功能
String[] tags() default "";
// 接口返回数据类型
String responseContainer() default "";
// 接口返回的引用类型
String responseReference() default "";
// 接口请求的方式
String httpMethod() default "";
// 接口别名
String nickname() default "";
// 隐藏接口
boolean hidden() default false;
// 获取响应头列表
ResponseHeader[] responseHeaders() default @ResponseHeader(name = "", response = Void.class);
// 接口状态码
int code() default 200;
// 可选的扩展数组
Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));
// 忽略@JsonView注释
boolean ignoreJsonView() default false;
}
value属性
和@Api的value属性作用一致，都是为了备注信息
notes属性
可以对相应的接口进行详细的信息的描述
@PostMapping("/login")
@ApiOperation(value = "用户登录接口",notes = "必须是POST请求,you know?")
public String login() {
return 用户登录;
}
tags属性
@ApiOperation中的tags参数和@Api中的tags参数有着异曲同工之妙，不同之处就在于。@Api中的tags是给每个接口类进行分组，而后者则是给每个单独的接口进行注释分组，下面来个例子就很容易看出。 需要注意的是，tags参数不能单独存在，所以必须配置一个value指定名称
@PostMapping("/login")
@ApiOperation(value = "用户登录接口", tags = {"login1", "login2"})
public String login() {
return 用户登录;
}
nickename属性
用于给一个接口命名
@PostMapping("/login")
@ApiOperation(value = "用户登录接口",nickname = "Login")
public String login() {
return 用户登录;
}
httpMethod属性
@PostMapping("/login")
@ApiOperation(value = "用户登录接口",httpMethod = "PUT")
public String login() {
return 用户登录;
}
上述的代码是例如将POST请求的登录接口标注为PUT请求方式
hidden属性
同样可以隐藏相应接口的API
3. @ApiModel注解
ApiModel注解描述的是项目中的实体类的类型，此注解提供了对实体类进行注释、说明的方法
注解源码
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface ApiModel {
// 指定实体类在文档中的名称
String value() default "";
// 实体描述信息
String description() default "";
// 指定一个继承的父类
Class<?> parent() default Void.class;
// 支持模型继承和多态性。
String discriminator() default "";
// 获取子类型的数组
Class<?>[] subTypes() default {};
// 对其它类型的引用。
String reference() default "";
}
value注解
用于给实体类起一个别名**
@Data
@ApiModel(value = "User类")
public class User implements Serializable {
private Long id;
private String username;
private String password;
}
description属性
给实体类添加描述信息
@Data
@ApiModel(value = "User类",description = "用户实体类")
public class User implements Serializable {
private Long id;
private String username;
private String password;
}
4. @ApiModelProperty注解
ApiModel是定义整个实体类的信息，那么ApiModelProperty后面加个Property顾名思义就是定义在属性上，也就是实体类中的字段。该注解功能相较ApiModel多一些，但大多也都是不常用的
注解源码
@Target({ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiModelProperty {
// 定义字段的描述信息
String value() default "";
// 定义一个名称
String name() default "";
// 限制参数接受的值
String allowableValues() default "";
// 过滤属性
String access() default "";
// 定义提示信息
String notes() default "";
// 定义参数数据类型，默认为字段本甚
String dataType() default "";
// 参数值是否必须传
boolean required() default false;
// 成员变量的顺序
int position() default 0;
// 是否隐藏参数
boolean hidden() default false;
// 定义属性的例子
String example() default "";
// 将字段定义为只读或可读可写
AccessMode accessMode() default AccessMode.AUTO;
// 引用对应类型的数据
String reference() default "";
// 是否允许传递空值
boolean allowEmptyValue() default false;
// 可选的扩展数组
Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));
// 对应accessMode的枚举类
enum AccessMode {
AUTO,
READ_ONLY,
READ_WRITE;
}
}
value属性
ApiModel中的value属性是对实体类进行描述说明。而在ApiModelProperty中的value属性则是对成员属性进行描述和说明
@Data
@ApiModel(value = "User类",description = "用户实体类")
public class User implements Serializable {
@ApiModelProperty(value = "这是对应数据库的主键Id")
private Long id;
@ApiModelProperty(value = "这是登录用户名")
private String username;
@ApiModelProperty(value = "这是登录密码")
private String password;
}
name属性
给属性起一个别名
@ApiModel(value = "User类",description = "用户实体类")
public class User implements Serializable {
@ApiModelProperty(notes = "主键id必须唯一、必须自增！！")
private Long id;
@ApiModelProperty(notes = "用户名必须填写！！")
private String username;
@ApiModelProperty(notes = "密码不能或缺！！")
private String password;
}
hiddens属性
和其它注解中作用一致，都是用来隐藏属性，只不过作用于不同，在ApiModelProperty中是用于隐藏属性字段的。
@ApiModel(value = "User类",description = "用户实体类")
public class User implements Serializable {
@ApiModelProperty(notes = "主键id必须唯一、必须自增！！")
private Long id;
@ApiModelProperty(notes = "用户名必须填写！！")
private String username;
@ApiModelProperty(notes = "密码不能或缺！！",hidden = true)
private String password;
}
example属性
放到字段上就是测试的时候起一个例子，以便于开发人员照着例子进行测试，达到见名知意的目的
@Data
@ApiModel(value = "User类",description = "用户实体类")
public class User implements Serializable {
@ApiModelProperty(notes = "主键id必须唯一、必须自增！！")
private Long id;
@ApiModelProperty(notes = "用户名必须填写！",example = "username = admin")
private String username;
@ApiModelProperty(notes = "密码不能或缺！！")
private String password;
}
5. @ApiParam注解
ApiParam注解的作用是给文档中接口测试的参数进行描述的，目的是为了可以快速理解每个参数的含义。该注解分别可以作用于参数、字段、方法上。一般常用于参数中，所以这篇文档使用参数注释的方式
源码解释
@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiParam {
// 指定文档中参数的名称
String name() default "";
// 指定文档中参数的描述
String value() default "";
// 指定文档中参数的默认值
String defaultValue() default "";
// 是否必须传值
boolean required() default false;
// 指定参数访问规则
String access() default "";
// 参数是否能接收多个值
boolean allowMultiple() default false;
// 是否隐藏参数
boolean hidden() default false;
// 定义单个参数的示例
String example() default "";
// 定义参数的示例
Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));
// 指定参数类型
String type() default "";
// 自定义格式
String format() default "";
// 将值设置为空
boolean allowEmptyValue() default false;
// 只读，默认false
boolean readOnly() default false;
}
name属性
在测试文档中为name参数指定名称
@ApiOperation(value = "用户登录接口")
public User login(@ApiParam(name = "用户名")
@RequestParam String username,
@ApiParam(name = "密码")
@RequestParam String password) {
return new User();
}
value属性
name和value的关系总是容易搞混，在ApiParam注解中是用来指定接口参数中的描述的
@ApiOperation(value = "用户登录接口")
public User login(@ApiParam(name = "用户名",value = "这里是用户名")
@RequestParam String username,
@ApiParam(name = "密码",value = "这里是密码")
@RequestParam String password) {
return new User();
}
defaultValue属性
default是默认的意思，value则是属性值的意思，字面来看就是定义一个默认的属性值以供参考
@ApiOperation(value = "用户登录接口")
public User login(@ApiParam(name = "用户名",value = "这里是用户名",defaultValue = "Bear")
@RequestParam String username,
@ApiParam(name = "密码",value = "这里是密码",defaultValue = "123456")
@RequestParam String password) {
return new User();
}
required属性
required 表示参数是否必须传递，true为必须，false为可选填
@ApiOperation(value = "用户登录接口")
public User login(@ApiParam(name = "用户名",value = "这里是用户名",defaultValue = "Bear",required = true)
@RequestParam String username,
@ApiParam(name = "密码",value = "这里是密码",defaultValue = "123456")
@RequestParam String password) {
return new User();
}
hidden属性属性
在文档中隐藏指定的参数值
@ApiOperation(value = "用户登录接口")
public User login(@ApiParam(name = "用户名",value = "这里是用户名")
@RequestParam String username,
@ApiParam(name = "密码",value = "这里是密码",hidden = true)
@RequestParam String password) {
return new User();
}
example属性
为参数指定传值的示例，和defaultValue功能类似
@ApiOperation(value = "用户登录接口")
public User login(@ApiParam(name = "用户名",value = "这里是用户名",example = "admin")
@RequestParam String username,
@ApiParam(name = "密码",value = "这里是密码",example = "123456")
@RequestParam String password) {
return new User();
}
930
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
