引言
————————————————————————————————————————————————————
最近在后台开发的时候,使用swagger2进行前后台接口文档的声明。由此遇见的一些问题,写下来给自己复习。
参考:
https://blog.csdn.net/xupeng874395012/article/details/68946676
正文
————————————————————————————————————————————————————
在进行整合swagger2的时候,首先引入swagger2的jar,由于我使用的是springboot,所以以springboot为例。
<!--springboot 集成 swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
引入swagger2的jar包之后,我们需要配置一个swagger2的配置类,来声明一些swagger2的配置信息
@Configuration //表示是配置类,要被加载
@EnableSwagger2 //swagger的配置
public class Swagger2 {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //添加ApiOperiation注解的被扫描
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
Contact contact = new Contact("xx", "www.baidu.com", "xxx@126.com");
return new ApiInfoBuilder()
.title("cc").contact(contact).description("接口文档").license("Apache License Version 2.0")
.version("v1.0").build();
}
}
这样的话,swagger2就已经配置完毕了。接下来你只需要在你的接口上配置你想要显示的信息即可。
接口上信息的配置如下:
@RestController
@Api(value = "user", tags = "用户模块")
@RequestMapping("user")
public class UserController extends BaseController {
@Resource
private UserService userService;
@ApiOperation(value = "用户添加")
@ApiImplicitParams({
@ApiImplicitParam(name = "user",value = "用户" ,required = true,dataType = "String", paramType = "body")
})
@RequestMapping(value = "addUser",method = RequestMethod.POST)
public ResultBean addUser(User user){
return resultBean;
}
}
关于其中@Api和@ApiOperation等的详细解释如下:
作用范围 | API | 使用位置 |
---|---|---|
对象属性 | @ApiModelProperty | 用于出入参数对象的字段上 |
协议集描述 | @Api | 用于Controller类上 |
协议描述 | @ApiOperation | 用在Controller的方法上 |
Response集 | @ApiResponses | 用在controller的方法上 |
Response | @ApiResponse | 用在 @ApiResponses里边 |
非对象参数集 | @ApiImplicitParams | 用在controller的方法上 |
非对象参数描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里边 |
描述返回对象的意义 | @ApiModel | 用在返回对象类上 |
关于参数的详细解释
属性 | 取值 | 作用 |
---|---|---|
paramType | 查询参数类型 | |
path | 以地址的形式提交数据 | |
query | 直接跟参数完成自动映射赋值 | |
body | 以流的形式提交 仅支持POST | |
header | 参数在request headers 里边提交 | |
form | 以form表单的形式提交 仅支持POST | |
dataType | 参数的数据类型 只作为标志说明,并没有实际验证 | |
Long | ||
String | ||
name | 接收参数名(必须与方法中参数名一致) | |
value | 接收参数的意义描述(描述信息) | |
required | 参数是否必填 | |
true | 必填 | |
false | 非必填 | |
defaultValue | 默认值 |
用在 @ApiResponses里边 |