springboot使用swagger2生成开发文档

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