引入jar包
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>```
java配置
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;
/**
* @author liushuntao
* @date 2023/5/18
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(Boolean.TRUE)
.select()
//指定对应的接口类
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
/* 设置安全模式,swagger可以设置访问token */
.securitySchemes(securitySchemes())
.securityContexts(securityContexts());
}
//接口文档的信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//标题
.title("Mqtt的API文档")
//描述
.description("Mqtt接口文档")
//版本号
.version("1.0")
.build();
}
/**
* 安全模式,这里指定token通过Authorization头请求头传递
*/
private List<ApiKey> securitySchemes() {
List<ApiKey> apiKeyList = new ArrayList<ApiKey>();
apiKeyList.add(new ApiKey("TOKEN", "TOKEN", "header"));
return apiKeyList;
}
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(
SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("^(?!auth).*$"))
.build());
return securityContexts;
}
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("TOKEN", authorizationScopes));
return securityReferences;
}
}
Swagger使用的注解
@Api:用在类上,说明该类的作用。
@ApiOperation:注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam:用来注解来给方法入参增加说明。
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
l code:数字,例如400
l message:信息,例如"请求参数没填好"
l response:抛出异常的类
@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:描述一个model的属性
用于类的注解
@Api:资源描述
标识这个类是 Swagger 的资源
@Api(tags = "商户相关接口")
@RestController
@RequestMapping("/merchants")
public class MerchantsController
- values:字符串;说明该类的作用,在类旁边的小字显示
- tags:字符串;标签(也可理解成分类),会替换 Controller 名称;当多个 Controller 的 tags 相同时,它们的方法会在一起显示
- consumes:字符串;指定处理请求的提交内容类型(Content-Type),例如 application/json
- produces:字符串;指定返回的内容类型,即仅当请求头的 Accept 类型中包含该指定类型才返回,例如:application/json
- protocols:字符串;标识当前的请求支持的协议,例如:http、https、ws
- hidden:true/false;隐藏整个 Controller,作用与 @ApiIgnore 相似,但没有 @ApiIgnore 功能强大
@ApiIgnore:资源过滤
@ApiIgnore 注解另一种是在 Docket 上增加筛选。两种方式的区别是,Docket 配置的规则,可以对多个接口器过滤作用,而 @ApiIgnore 只能作用于单个接口。
如果想在文档中屏蔽掉删除用户的接口(user/delete),那么只需要在删除用户的方法上加上 @ApiIgnore 即可。
2.用于方法的注解
@ApiOperation:方法描述
@ApiOperation(value = "创建商户", notes = "开发中")
public Response createMerchants
- value:字符串;方法摘要,在路径旁显示
- note:字符串;方法详细描述
- tags:字符串数组;对方法进行分类,一个方法可以有多个分类
- response:Class;设置当前请求的返回值类型,String.class;会覆盖自动识别的返回类型,一般用不上
- responseContainer:字符串;说明包装的容器,默认情况下,有效值为 List、Set、Map;在定义通用 Response 后,一般用不上
- httpMethod:字符串;指定请求方式,比如 GET、POST、PUT
- consumes:字符串;指定处理请求的提交内容类型(Content-Type),例如 application/json
- produces:字符串;指定返回的内容类型,即仅当请求头的 Accept 类型中包含该指定类型才返回,例如:application/json
@ApiImplicitParam(s):参数描述
参数描述,可用在方法头。
ApiImplicitParams 只有一个属性 ApiImplicitParam[] value(); 是 ApiImplicitParam 的数组,比如
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "商户ID")
})
@GetMapping("/{id}")
public Response getMerchantsInfo(@PathVariable Integer id) {
return null;
}
所以,来看看 @ApiImplicitParam 有哪些属性:
-
name:字符串;参数名
-
value:字符串;参数的汉字说明、解释
-
defaultValue:字符串;参数的默认值
-
allowableValues:字符串;限制此参数接收的值,可使用的值或值得范围
(表示是大于,)表示是小于
[表示是大于等于,]表示是小于等于
infinity表示无限大,-infinity表示负无限大 -
allowEmptyValue:true/false;允许参数为空,默认为 false
-
required:true/false;参数是否必须传
-
paramType:字符串;参数放在哪个地方(可以自动识别)
-
header --> 参数在request headers 里边提交:@RequestHeader
path(用于restful接口)–> 参数以地址的形式提交:@PathVariable
query --> 直接跟参数完成自动映射赋值:@RequestParam
form --> 以form表单的形式提交,仅支持POST:@RequestParam
body --> 以流的形式提交,仅支持POST:@RequestBody -
dataType:字符串;参数类型,参数的数据类型(默认String),可以使用类名或原始数据类型(使用不当汇报类型转换异常)
-
dataTypeClass:Class;参数的类,如果提供则覆盖 dataType
-
example:字符串;非请求体(body)参数的单个请求示例
-
examples:Example;参数的举例说明,仅适用于 body 类型。
@ApiParam:参数描述
参数描述,用在每个参数前面,比如
@PostMapping("/create")
// 注:这里如果使用 @ApiImplicitParam 会出现无法识别的问题
public Response createMerchants(
@ApiParam(name = "request", value = "创建商户请求对象") @RequestBody CreateMerchantsRequest request)
@ApiParam 的可以设置的属性如下:
- name:字符串;参数名
- value:字符串;参数的汉字说明、解释
- defaultValue:字符串;参数默认值
- allowableValues:字符串;限制此参数接收的值,可使用的值或值得范围
- (表示是大于,)表示是小于
- [表示是大于等于,]表示是小于等于
- infinity表示无限大,-infinity表示负无限大
- allowEmptyValue:true/false;允许参数为空,默认为 false
- required:true/false;参数是否必须传
- example:字符串;非请求体(body)参数的单个请求示例
- examples:Example;参数的举例说明,仅适用于 body 类型。
关于 @ApiImplicitParam 和 @ApiParm 它俩都能为方法的请求参数做注释,区别有:
@ApiImplicitParam 可以在方法前使用,而 @ApiParm 只能在参数前使用
@ApiImplicitParam 提供的可设置属性更多,特别是 paramType 很关键
对于 @RequestBody 标识的 Json 字符串,不能使用 @ApiImplicitParam,会出现无法识别的情况
方案一:通过 @ApiParm 对 @RequestBody 的参数进行说明
方案二:直接不对该参数使用注解,将注释的任务交给实体类(@ApiModel)
另外,两者是可以混搭使用的,一般推荐使用 @ApiImplicitParam(s),但是注意 @RequestBody 的情况。
@ApiResponse(s)
跟上面 @ApiImplicitParam(s) 一样,@ApiResponses 也是只有唯一个属性ApiResponse[] value();
@ApiResponses({
@ApiResponse(code = 1, message = "非HTTP状态码,Response code字段值,描述:成功,返回该商户ID"),
@ApiResponse(code = 0, message = "非HTTP状态码,Response code字段值,描述:失败")
})
@PostMapping("/create")
public Response createMerchants
下面来看看 @ApiResponse 有哪些属性
- code:整形数;相应的状态码
- message:字符串;相应消息,例如"电话号码已存在"
- response:Class;消息有效负载的可选响应类,对应于响应消息对象的 schema 字段;对于使用通用 Response 的情况,该字段很关键
- responseHeaders:ResponseHeader[];可能响应的 header 列表
- responseContainer:String;声明响应的容器,有效值为List,Set,Map,任何其他值都将被忽略
3.用于实体类的注解
@ApiModel:实体类描述
用于请求类或者响应类上,表示一个返回响应数据的信息
@ApiModel("创建商户的请求对象")
@Data
@AllArgsConstructor
@NoArgsConstructor
public class CreateMerchantsRequest
- value:字符串;实体类的备用名,如果不设置,则会采用原类名
- description:字符串;实体类的说明
- parent:Class;父类的一些信息
@ApiModelProperty:实体类成员描述
@ApiModel("创建商户的请求对象")
@Data
@AllArgsConstructor
@NoArgsConstructor
public class CreateMerchantsRequest {
@ApiModelProperty("商户名")
private String name;
@ApiModelProperty("商户logo的URL")
private String logoUrl;
@ApiModelProperty("营业执照URL")
private String businessLicenseUrl;
@ApiModelProperty("联系电话")
private String phone;
@ApiModelProperty("地址")
private String address;
}
ApiModelProperty 可以设置的属性有:
- value:字符串;字段说明
- name:字符串;重写字段名称
- dataType:字符串;重写字段类型
- required:true/false;是否必填
- allowableValues:字符串;限制此参数接收的值,可使用的值或值得范围
- (表示是大于,)表示是小于
- [表示是大于等于,]表示是小于等于
- infinity表示无限大,-infinity表示负无限大 - allowEmptyValue:true/false;允许参数为空,默认为 false
- example:String;示例
- hidden:true/false;是否在文档中隐藏该字段