一、swagger常用注解
1、与模型相关的注解
两个注解:
-
@ApiModel:用在模型类上,对模型类做注释;
@ApiModelProperty:描述一个model的属性
-
@ApiModelProperty:用在属性上,对属性做注释
2、与接口相关的注解
六个注解:
- @Api:用在controller上,对controller进行注释;
- @ApiOperation:用在API方法上,对该API做注释,说明API的作用;
- @ApiImplicitParams:用来包含API的一组参数注解,可以简单的理解为参数注解的集合声明;
- @ApiImplicitParam:用在@ApiImplicitParams注解中,也可以单独使用,说明一个请求参数的各个方面,该注解包含的常用选项有:
paramType:参数所放置的地方,包含query、header、path、body以及form,最常用的是前四个。
name:参数名;
dataType:参数类型,可以是基础数据类型,也可以是一个class;
required:参数是否必须传;
value:参数的注释,说明参数的意义;
defaultValue:参数的默认值;
-@ApiResponses:通常用来包含接口的一组响应注解,可以简单的理解为响应注解的集合声明;
- @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:即httpCode,例如400 - message:信息,例如"请求参数没填好"
二、创建Swagger2配置类
在Application.java同级创建Swagger2的配置类Swagger2
package com.swaggerTest;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Swagger2配置类
* 在与spring boot集成时,放在与Application.java同级的目录下。
* 通过@Configuration注解,让Spring来加载该类配置。
* 再通过@EnableSwagger2注解来启用Swagger2。
*/
@Configuration
@EnableSwagger2
public class Swagger2 {
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
* 本例采用指定扫描的包路径来定义指定要建立API的目录。
*
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.swaggerTest.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 创建该API的基本信息(这些基本信息会展现在文档页面中)
* 访问地址:http://项目实际地址/swagger-ui.html
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多请关注http://www.baidu.com")
.termsOfServiceUrl("http://www.baidu.com")
.contact("sunf")
.version("1.0")
.build();
}
}
如上代码所示,通过createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。
完成上述代码添加上,启动Spring Boot程序,访问:http://localhost:8080/swagger-ui.html
如上图,可以看到暴漏出来的控制器信息,点击进入可以看到详细信息。
两个注意点:
- paramType会直接影响程序的运行期,如果paramType与方法参数获取使用的注解不一致,会直接影响到参数的接收。
例如:
使用Sawgger UI进行测试,接收不到!
2.Conntroller中定义的方法必须在@RequestMapper中显示的指定RequestMethod类型,否则SawggerUi会默认为全类型皆可访问, API列表中会生成多条项目。
如上图:updatePassword()未指定requestMethod,结果生成了7条API信息。所以如果没有特殊需求,建议根据实际情况加上requestMethod。