Spring Boot -- Swagger之自定义文档说明

项目说明

@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.any())                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("Spring Boot整合Swagger测试项目")                .description("测试测试")                .contact("yucoang")                .version("1.0")                .build();    }}

在ApiInfo对象中,可进行title(标题),description(描述),contact(作者),version(版本)的信息说明.

分组说明

在Swagger中,默认以一个Controller类为一个分组,并以Controller类名作为组名与描述
可在Controller中使用@Api设置信息说明.

@Api("Hello模块")@RestController@RequestMapping("/hello")public class HelloContrller {    ...}

属性 说明 默认值 value 分组名称 controller名 description 分组说明 controller名

Api说明

在Swagger中,默认以方法名作为API名称.可在方法上使用@ApiOperation设置信息说明

@ApiOperation(value = "say hello", notes="return Hello World")@GetMapping("/say")public String sayHello(){    return "Hello World";}

属性 说明 默认值 value 接口名称 方法名 notes 接口说明 空

Api参数说明

在Swagger中,当接口存在参数时,会自动生成参数文档

接口注释

可以使用@ApiImplicitParams与@ApiImplicitParam自定义参数说明

@ApiOperation(value = "say hello", notes="return Hello World")@ApiImplicitParams({    @ApiImplicitParam(name="user",value="用户名",dataType="string",paramType="query",required=true)})@GetMapping("/say")public String sayHello(@RequestParam String user){    return user + " say : Hello World";}

属性 说明 可选值 name 参数名 value 参数说明 dataType 参数类型 原始数据类型(string,int,long等)或class名 paramType 参数方式 query,path,body,header,form required 是否必填 true,false allowMultiple 允许多个值 true,false defaultValue 默认值 allowableValues 允许的值 access

name : 参数名

必须与实际参数传入变量名一致.,显示在Parameters表格的Parameter列

value : 参数说明

可任意填写,显示在Parameters表格的Description列

paramType 参数方式

根据参数的传入方式

值 对应参数传入方式 query @RequestParam,@ModelAttribute path @PathVariable body @RequestBody header @RequestHeader

dataType:参数类型

可以是简单数据类型,如string,int,long等,也可以是一个类的类名
当dataType是一个自定义类时,参考Api自定义类说明

required:是否必填

值为true或false.
当值为true时,Parameters表格的Parameter列与Description列为粗体,且value列的输入框显示required,该输入框为空时将会阻止提交操作

allowMultiple:允许多值

值为true或false
当为true时,输入框可使用”,”连接多个值,参数必须为数组或列表才可使用该属性

defaultValue :默认值

该属性有值时,Parameters表格的value列输入框默认填入该值

allowableValues :允许的值的数组

该属性有值时,Parameters表格的value列输入框将改为下拉列表,列表项为该值

全局参数

@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(this.apiInfo())                .select()                .apis(RequestHandlerSelectors.any())                .paths(PathSelectors.any())                .build()                .globalOperationParameters(this.globalParameters());    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("Spring Boot整合Swagger测试项目")                .description("测试测试")                .contact("yucoang")                .version("1.0")                .build();    }    private List<Parameter> globalParameters(){        List<Parameter> aParameters = new ArrayList<Parameter>();        ParameterBuilder p1 = new ParameterBuilder();        p1            .name("token")            .description("token")            .modelRef(new ModelRef("string"))            .parameterType("header")            .required(true)            .defaultValue("")            .build();        aParameters.add(p1.build());        return aParameters;     }}

Api返回值

接口注释

可以使用@ApiResponses与@ApiResponse自定义参数说明

@ApiOperation(value = "say hello", notes="return Hello World")@ApiResponses({    @ApiResponse(code=500,message="失败"),    @ApiResponse(code=501,message="内部异常")})@GetMapping("/say")public String sayHello(@RequestParam String user){    ...}

属性 说明 code HTTP Status 码 message 说明

全局返回值

@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(this.apiInfo())                .select()                .apis(RequestHandlerSelectors.any())                .paths(PathSelectors.any())                .build()                .globalResponseMessage(RequestMethod.GET,this.globalResponseMessage());    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("Spring Boot整合Swagger测试项目")                .description("测试测试")                .contact("yucoang")                .version("1.0")                .build();    }    private List<ResponseMessage> globalResponseMessage(){        List<ResponseMessage> aResponses = new ArrayList<>();        aResponses.add(new ResponseMessage(201, "Created/已创建", null));        aResponses.add(new ResponseMessage(401, "Unauthorized/未授权", null));        aResponses.add(new ResponseMessage(403, "Forbidden/禁止", null));        aResponses.add(new ResponseMessage(404, "地址不存在", null));        return aResponses;    }}

Api自定义类说明

当参数类型为RequestBody时，参数可能为POJO对象。这时@ApiImplicitParam的属性dataType便不再是简单数据类型，而是一个自定义的实体类。

@PutMappingpublic String say2(@RequestBody User user){    return "Hello World";}public class User {    private Long id;    private String name;    private Boolean sex;    //Getting and Setting   }

这时可以通过@ApiModel与@ApiModelProperty对User实体类进行设置

@ApiModel("User")public class User {    @ApiModelProperty(hidden=true)    private Long id;    @ApiModelProperty(name="name",value="用户姓名")    private String name;    @ApiModelProperty(name="sex",value="用户性别")    private Boolean sex;}

@ApiModel

属性 说明 value Swagger Model名

@ ApiModelProperty

属性 说明 name 变量名 value 变量说明 hidden 是否隐藏

当@ApiModel的value省略时，默认将类名作为SwaggerModel，即@ApiImplicitParam的dataType可直接为该实体类名。

参考网址:http://docs.swagger.io/swagger-core/v1.5.0/apidocs/io/swagger/annotations/package-summary.html