上一篇异常处理我们讲解了关于异常的处理,本文主要介绍对于API的处理。
本文项目地址:
现在Spring对于web的处理分成2中方式:
一种是传统的webmvc的方式,基于http的
一种是基于reactor和netty实现的,webflux的方式。
因此Swagger也提供了2种集成方式,
webflux的实现
Swagger2集成Spring boot 2.1.12 基于WebFlux
可以看这篇文章,里面有详细的说明
Web的实现
POM的引入
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-bean-validators</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
配置实现
/**
* API文档配置
*
* @author 大仙
*
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi(){
ParameterBuilder builder = new ParameterBuilder();
builder.parameterType("header").name(Constant.AUTHORIZATION)
.description("header参数")
.required(false)
.modelRef(new ModelRef("string")); // 在swagger里显示header
return new Docket(DocumentationType.SWAGGER_2).groupName("-接口文档")
.apiInfo(new ApiInfoBuilder().title("接口文档")
.contact(new Contact("朱维", "", "XXX")).version("1.0").build())
.globalOperationParameters(Lists.newArrayList(builder.build()))
.select()
.apis(RequestHandlerSelectors.basePackage("com"))
.paths(PathSelectors.any()).build();
}
}
这样配置完成就OK了
Swagger使用
@Api:用在类上,说明该类的作用。
@ApiOperation:注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam:用来注解来给方法入参增加说明。
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
l code:数字,例如400
l message:信息,例如"请求参数没填好"
l response:抛出异常的类
@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
l @ApiModelProperty:描述一个model的属性
注意:@ApiImplicitParam的参数说明:
paramType:指定参数放在哪个地方 |
header:请求参数放置于Request Header,使用@RequestHeader获取 query:请求参数放置于请求地址,使用@RequestParam获取 path:(用于restful接口)-->请求参数的获取:@PathVariable body:(不常用) form(不常用) |
name:参数名 |
|
dataType:参数类型 |
|
required:参数是否必须传 |
true | false |
value:说明参数的意思 |
|
defaultValue:参数的默认值 |
访问
启动相应的服务之后访问:http://localhost:端口/swagger-ui.html