- 添加依赖
pom.xml
<!--JSON API文档的生成-->
<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>
- 创建swagger配置文件
SwaggerConfig.java
@Configuration
@EnableSwagger2
@ConditionalOnExpression("${swagger.enable:true}")
public class SwaggerConfig {
@Bean
public Docket swaggerSpringMvcPlugin(){
ApiInfo apiInfo = new ApiInfoBuilder()
.title("** APIs")
.description("**的接口文档")
.version("1.0.0")
.termsOfServiceUrl(null)
.contact(new Contact("name", "url", "email"))
.license("作者:**")
.licenseUrl("http://")
.build();
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.select()
//.paths(regex("/api/*")) // 指定接口url
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo)
.useDefaultResponseMessages(false);
return docket;
}
}
- 配置具体的接口注释数据的简单示例,更多的注释可参看官网
- @Api() 用于controller类
- @ApiOperation()用于controller的方法
ApiOperation(value = "/api/edit", notes = "", httpMethod = "POST", response = Response.class)
- @ApiResponses用于controller的方法,响应的数据
@ApiResponses({
@ApiResponse(code = 100 , message = "请选择部门"),
@ApiResponse(code = 101, message = "请选择日期")
})
- @ApiImplicitParams()用于controller的方法,参数注释
@ApiImplicitParams({
@ApiImplicitParam(name = "department", value = "部门", required = true, paramType = "form"),
@ApiImplicitParam(name = "date", value = "日期", required = true, paramType = "form")
})
name 参数
value 参数的描述
required 是否必传
paramType 参数存放位置:header、query、path(resuful接口)、body、form
dataType 参数类型
defaultValue 参数默认值
- @ApiModel() 用于bean对象的类
@ApiModel(value = "", description = "")
- @ApiModelProperty()(用于bean对象的方法
@ApiModelProperty(value = "", name="")
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏
- @ApiParam()具体请求参数
@ApiParam(name = "", value = "", required = true)
name 参数
value 参数简单描述
defaultValue 描述参数默认值
allowableValues 可接收参数值限制
required 是否为必传参数
- 与spring security配合
使用了spring security时,需要登录访问,或者在security配置文件中添加对url的忽略。
public class WebSecurityConfig extends WebSecurityConfigurerAdapter {
@Override
public void configure(WebSecurity web) throws Exception {
web.ignoring().antMatchers(
"/swagger-ui.html",
"/webjars/**",
"/v2/api-docs",
"/swagger-resources",
"/swagger-resources/configuration/ui",
"/swagger-resources/configuration/security"
);
}
}
5.访问 ip:port/swagger-ui.html
- 控制swagger关闭和启动
SwaggerConfig.java
中添加注释@ConditionalOnExpression("${swagger.enable:true}")
application.properties
更改:true
启动,false
关闭,线上系统需要关闭。
网友评论