Springfox - Swagger2 常用注解

@ApiIgnore()：用于类或者方法上，可以不被swagger显示在页面上

@Api()：用于类表示标识这个类是swagger的资源

tags–表示说明 但是tags如果有多个值，会生成多个list
value–也是说明，可以使用tags替代 （实际没有作用）

@ApiOperation()：用于方法；表示一个http请求的操作

value用于方法描述 
notes用于提示内容 
tags可以重新分组（视情况而用）

@ApiImplicitParams()：用于方法，包含多个 @ApiImplicitParam

name–参数ming 

value–参数说明 

required 是否必须 boolean

dataType–数据类型 
paramType–参数类型 

    body 使用@RequestBody接收数据 POST有效
    path 在url中配置{}的参数
    query 普通查询参数 例如 ?query=q ,jquery ajax中data设置的值也可以，例如 {query:”q”},springMVC中不需要添加注解接收
    header 使用@RequestHeader接收数据
    form 笔者未使用，请查看官方API文档

example–举例说明

@ApiImplicitParam()： 用于方法 表示单独的请求参数

表示单独的请求参数 

@ApiResponses()：用于表示一组响应

@ApiResponse()：用在@ApiResponses中，一般用于表达一个错误的响应信息

code：数字，例如400

message：信息，例如"请求参数没填好"
　 response：抛出异常的类

@ApiParam()：用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）

name–参数名 
value–参数说明 
required–是否必填 

@ApiModel()：用于类 表示对类进行说明，用于参数用实体类接收

value–表示对象名 
description–描述 
都可省略 

@ApiModelProperty()：用于方法，字段 表示对model属性的说明或者数据操作更改

value–字段说明 
required–是否必填 
name–重写属性名字  
dataType–重写属性类型
example–举例说明 
hidden–隐藏

---

• demo

import com.max256.morpho.sys.entity.TestEntity;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

@Api(tags = "表示说明") // 标识这个类是swagger的资源
@RestController
@RequestMapping("/test")
public class TestController {

    @ApiOperation(value = "方法描述",notes = "提示内容",httpMethod = "get") // 用于方法；表示一个http请求的操作
    @ApiImplicitParams({
            @ApiImplicitParam(name = "s",value = "参数说明",required = true,dataType = "string",example = "start"),
            @ApiImplicitParam(name = "n",value = "参数说明",required = false,dataType = "string",example = "end")
    })
    @ApiResponses({
            @ApiResponse(code = 200,message = "success_",response = String.class),
            @ApiResponse(code = 500,message = "error_",response = String.class),
    })
    @RequestMapping(value = "/test", method = RequestMethod.GET)
    public String test(
            String s,String n
            // 此处使用@ApiParam Swagger解析会出问题,但不影响请求
//             @ApiParam(name = "s",value = "s参数",required = true,example = "start") String s,
//             @ApiParam(name = "n",value = "n参数",required = false,example = "start") String n
    ){
        return s + " - test - " + n;
    }

    @ApiOperation(value = "方法描述",notes = "提示内容",httpMethod = "post")
    @RequestMapping(value = "/testEntity",method = RequestMethod.POST)
    public TestEntity testEntity(@RequestBody TestEntity testEntity){

        return testEntity;
    }

    @RequestMapping(value = "/testPathVarible/{param}",method = RequestMethod.GET)
    public String TestPathVarible(@ApiParam(name = "param",value = "参数说明",required = true)@PathVariable(name = "param") String params){

        return params;
    }
}

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.ToString;

@ApiModel
@Data
@NoArgsConstructor
@AllArgsConstructor
@ToString
public class TestEntity {

    @ApiModelProperty(name = "name",value = "姓名",example = "lb")
    private String name;
    @ApiModelProperty(hidden = true)
    private String value;
    @ApiModelProperty(name = "age",value = "年龄",example = "16")
    private int age;

}