使用swagger2生成API
pom.xml swagger2 和 swagger-ui
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.1.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.1.2</version>
</dependency>
@EnableSwagger2
@Configuration
public class ApiConfig {
@Bean
public Docket getDocket(){
// 生成有@Api标签的类的所有的api
return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withClassAnnotation(Api.class)).build();
}
}
@Component
public class SwaggerMvcConfigurerAdapter extends WebMvcConfigurerAdapter {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html").addResourceLocations(
"classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations(
"classpath:/META-INF/resources/webjars/");
}
}
1、@Api注解的使用:贴在类上,主要用下面的这几个属性
1)value:该controller简短的标题
2)description:详细介绍
3)producer:说明该controller是使用什么表现形式的
4)protocols:使用什么协议
2、@ApiOperation注解的使用:贴在方法上,主要用下面的这几个属性
1)value:该方法简短的标题
2)note:详细介绍
3)code:正常情况下返回的状态码是多少
4)httpMethod:使用什么http方法
5)response:响应什么对象,这里写的是响应的对象的字节码
@ApiImplicitParams@ApiImplicitParam和注解的使用,贴在参数上
1)name:参数名
2)value:参数名对应的值
3)dataType:参数的类型
4)require:该参数是否必填
5)paramType:该参数的来源类型,它的值有如下:
query:该参数从地址栏问号后面的参数获取
form:该参数从form表单中获取
path:该参数从URL地址上获取
body:该参数从请求体中获取
header:该参数从请求头获取
两种不生成api的方式:
1、@APIIgnore:可以贴在类和方法上
2、在swagger配置类上的select()方法上调用apis(),apis方法需要传入一个selector。可以使用RequestHandlerSelector内置的selector
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息(200相应不写在这里面)
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出的异常类
@ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:描述一个model的属性