一、引入jar包
<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>
二、创建swagger2的配置类
@Configuration @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi(){ //多个暴露路径时 //com.google.common.base.Predicate<RequestHandler> selector1 = RequestHandlerSelectors.basePackage("com.dingzi.project.Controller"); //com.google.common.base.Predicate<RequestHandler> selector2 = RequestHandlerSelectors.basePackage("com.dingzi.project.apiController"); return new Docket(DocumentationType.SWAGGER_2) //API基本信息 .apiInfo(apiInfo()) .select() //暴露路径为当前包路径 .apis(RequestHandlerSelectors.basePackage("com.example.learn.swagger2")) //多个暴露路径 //.apis(Predicates.or(selector1,selector2)) .paths(PathSelectors.any()) .build(); } //构建 api文档的详细信息函数,注意这里的注解引用的是哪个 private ApiInfo apiInfo() { return new ApiInfoBuilder() //页面标题 .title("Spring Boot 测试使用 Swagger2") //创建人、路径、邮箱 .contact(new Contact("dingzi", "", "")) //版本号 .version("1.0") //描述 .description("API 描述") .build(); } }
三、使用swagger2注解
@RestController @RequestMapping("/api") @Api("swagger2Controller测试api") @Slf4j public class SwaggerDemoController { @Autowired private UserService userService; @ApiOperation(value = "根据id查询用户", notes = "查询用户信息") @ApiImplicitParam(name = "id",value = "用户id",required = true) @RequestMapping(value = "/getuser/{id}",method = RequestMethod.GET) public User getUser(@PathVariable String id){ return userService.getUser(id); } }
- 在controller上的注解
@Api:用在controller上,表示对类的说明。一般为
@Api("swagger2Controller测试api") 常用参数: tags="说明该类的作用,非空时将覆盖value的值" value="描述类的作用" 其他参数: description 对api资源的描述,在1.5版本后不再支持 basePath 基本路径可以不配置,在1.5版本后不再支持 position 如果配置多个Api 想改变显示的顺序位置,在1.5版本后不再支持 produces 设置MIME类型列表(output),例:"application/json, application/xml",默认为空 consumes 设置MIME类型列表(input),例:"application/json, application/xml",默认为空 protocols 设置特定协议,例:http, https, ws, wss。 authorizations 获取授权列表(安全声明),如果未设置,则返回一个空的授权值。 hidden 默认为false, 配置为true 将在文档中隐藏
- 用于方法上(说明参数的含义)
@ApiOperation:方法的说明 一般为
@ApiOperation(value = "根据id查询用户", notes = "查询用户信息") 常用参数: value="说明方法的用途、作用" notes="方法的备注说明" 其他参数: tags 操作标签,非空时将覆盖value的值 response 响应类型(即返回对象) responseContainer 声明包装的响应容器(返回对象类型)。有效值为 "List", "Set" or "Map"。 responseReference 指定对响应类型的引用。将覆盖任何指定的response()类 httpMethod 指定HTTP方法,"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH" position 如果配置多个Api 想改变显示的顺序位置,在1.5版本后不再支持 nickname 第三方工具唯一标识,默认为空 produces 设置MIME类型列表(output),例:"application/json, application/xml",默认为空 consumes 设置MIME类型列表(input),例:"application/json, application/xml",默认为空 protocols 设置特定协议,例:http, https, ws, wss。 authorizations 获取授权列表(安全声明),如果未设置,则返回一个空的授权值。 hidden 默认为false, 配置为true 将在文档中隐藏 responseHeaders 响应头列表 code 响应的HTTP状态代码。默认 200 extensions 扩展属性列表数组
2、@ApiImplicitParams、@ApiImplicitParam:方法的参数的说明;@ApiImplicitParam 用于指定单个参数的说明,@ApiImplicitParams包含多个@ApiImplicitParam 一般为
@ApiImplicitParam(name = "id",value = "用户id",required = true)
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
@ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
name:参数名,参数名称可以覆盖方法参数名称,路径参数必须与方法参数一致
value:参数的汉字说明、解释
required:参数是否必须传,默认为false [路径参数必填]
paramType:参数放在哪个地方
·header --> 请求参数的获取:
@RequestHeader
·query --> 请求参数的获取:
@RequestParam
·path(用于restful接口)--> 请求参数的获取:
@PathVariable
·body(不常用)
·form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
3、@ApiResponses、@ApiResponse:方法返回值的状态码说明 一般为
@ApiResponse(code = 200, message = "请求成功"); @ApiResponses({ @ApiResponse(code = 200, message = "请求成功"), @ApiResponse(code = 400, message = "请求参数没填好"), @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对") }) @ApiResponses:方法返回对象的说明 @ApiResponse:每个参数的说明 code:数字,例如400 message:信息,例如"请求参数没填好" response:抛出异常的类
- 用于对象上(当请求数据描述,即
@RequestBody
时, 用于封装请求(包括数据的各种校验)数据;当响应值是对象时,即@ResponseBody
时,用于返回值对象的描述。)
1、@ApiModel:用于JavaBean上面,表示对JavaBean 的功能描述 一般为
@ApiModel(value="用户登录信息", description="用于判断用户是否存在") 参数: value–表示对象名
description–描述
2、@ApiModelProperty:用在JavaBean类的属性上面,说明属性的含义 一般为
@ApiModelProperty(value="用户名") 参数: value–字段说明 name–重写属性名字 dataType–重写属性类型 required–是否必填 example–举例说明 hidden–隐藏
- 用于方法参数上
1、@ApiParam() 用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等) 一般为
@ApiParam(name="id",value="用户id",required=true) 参数为:name–参数名 value–参数说明 required–是否必填