dinghaoran

一、引入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–是否必填    


分类:

技术点:

相关文章: