使用步骤:
-
引入swagger和swagger-ui的maven依赖
<!-- swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <!-- swagger2 ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>
- 启动类上加上启用swagger2的注解:@EnableSwagger2
- 编写swagger2的配置类
import org.springframework.beans.factory.annotation.Value; 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.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @Configuration public class Swagger2Config { //动态配置多环境是否开启 @Value("${swagger2.enable}") private boolean swagger2Enable; /** * Docket类:一个用于作为进入swagger-springmvc框架的主要接口的构建器。提供合理的默认设置和方便的配置方法 * @return */ @Bean public Docket createApiDocket() { return new Docket(DocumentationType.SWAGGER_2) .enable(swagger2Enable)//动态配置是否开启swagger,生产环境设置为false .groupName("延庆版本")//设置栏目名称,如果包含多个栏目,只需要将该生成Docket的方法复制多份,修改方法名和gropname的名称(不支持多个Docket用同样的groupName)和即可 .pathMapping("/")//设置api根路径 .apiInfo(apiInfo())//也可以不通过方法直接在参数中new出来 .select()//启动用于api选择的构造器。返回api选择生成器。要完成api选择器的构建,需要调用api选择器的构建方法,这将在调用build()方法时自动返回到构建docket .apis(RequestHandlerSelectors.basePackage("com.cloudplatform.hjy.controller"))// controller路径 .paths(PathSelectors.any()) .build(); } @Bean public Docket createApiDocketSpare() { return new Docket(DocumentationType.SWAGGER_2) .enable(swagger2Enable) .groupName("备用栏目") .pathMapping("/") .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.cloudplatform.hjy.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder().title("平台接口文档") .description("API文档描述").contact(new Contact("BooleanZhang", "https://blog.csdn.net/bebmwnz", "247275710@qq.com")) .version("0.0.1").build(); } }
-
接口中使用
a) controller上加上@Api
b) 方法中使用@Api和@ApiImplicitParam,
如果多个参数可以使用@Api@ApiImplicitParams(@ApiImplicitParam,@ApiImplicitParam……)@ApiOperation("根据参数,按照type_id分组统计总重量") @ApiImplicitParams({ @ApiImplicitParam(name="subjectId",value="责任主体id",dataType="String", paramType = "query",required=true), @ApiImplicitParam(name="startDate",value="开始日期",dataType="String", paramType = "query",required=true), @ApiImplicitParam(name="endDate",value="结束日期",dataType="String", paramType = "query",required=true) })
效果展示
参数介绍
@Api:用在请求的类上,表示对类的说明
tags="说明该类的作用,可以在UI界面上看到的注解"
value="该参数没什么意义,在UI界面上也看到,所以不需要配置"
@ApiOperation:用在请求的方法上,说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
@ApiResponses:用在请求的方法上,表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiModel:用于响应类上,表示一个返回响应数据的信息
(这种一般用在post创建的时候,使用@RequestBody这样的场景,
请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:用在属性上,描述响应类的属性
地址访问
http://ip:port/swagger-ui.html