swager2

概述

通过注解，快速生成api文档（类似java的doc）

使用

依赖

<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 Swagger2Config {

    @Bean
    public Docket webApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                //只显示api路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();

    }

    @Bean
    public Docket adminApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                //只显示admin路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();

    }

    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("网站-API文档")
                .description("本文档描述了网站微服务接口定义")
                .version("1.0")
                .contact(new Contact("goku", "http://goku.com", "2356498584@qq.com"))
                .build();
    }

    private ApiInfo adminApiInfo(){

        return new ApiInfoBuilder()
                .title("后台管理系统-API文档")
                .description("本文档描述了后台管理系统微服务接口定义")
                .version("1.0")
                .contact(new Contact("goku", "http://goku.com", "2356498584@qq.com"))
                .build();
    }

}

swager2可视化访问地址

常用注解

• @Api：描述类信息（controller）

  • tags：“说明该类的作用”

• @ ApiOperation：描述接口、方法

  • value=“说明方法的作用”
  • notes=“方法的备注说明”

• @ApiImplicitParams、@ApiImplicitParam：描述方法参数

  @ApiImplicitParams：用在请求的方法上，包含一组参数说明
  	@ApiImplicitParam：对单个参数的说明	    
      	name：参数名
      	value：参数的说明、描述
      	required：参数是否必须必填
      	paramType：参数放在哪个地方
          	· query --> 请求参数的获取：@RequestParam
          	· header --> 请求参数的获取：@RequestHeader	      
          	· path（用于restful接口）--> 请求参数的获取：@PathVariable
          	· body（请求体）-->  @RequestBody User user
          	· form（普通表单提交）	   
      	dataType：参数类型，默认String，其它值dataType="Integer"	   
    		defaultValue：参数的默认值
    		
  @Api(tags="用户模块")
  @Controller
  public class UserController {
  
  	@ApiOperation(value="用户登录",notes="随边说点啥")
  	@ApiImplicitParams({
  		@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
  		@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
  		@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
  	})
  	@PostMapping("/login")
  	public JsonResult login(@RequestParam String mobile, @RequestParam String password,
  	@RequestParam Integer age){
  		//...
  	    return JsonResult.ok(map);
  	}
  }
  		
  

• @ApiResponses、@ApiResponse：方法返回值的状态码说明

  @ApiResponses：方法返回对象的说明
  	@ApiResponse：每个参数的说明
  	    code：数字，例如400
  	    message：信息，例如"请求参数没填好"
  	    response：抛出异常的类
  

• @Model：描述javabean

  @ApiModel(description = "xxxx")
  

• @ApiModelProperty：用在JavaBean类的属性上面，说明属性的含义

  @ApiModelProperty(value = "错误码")
  private Integer errCode;