Swagger注解 传参

[@Api]

@ Api用于声明Swagger资源API。 它有双重用途 - 它会

影响资源列表_和_ API声明。 只有使用@ Api注释的类才会被Swagger扫描。

在资源清单中，注释将转换为[资源对象]

在API声明中，它基本上将作为[API声明]本身的基础。

JAX-RS的用法是:

@Api(tags = "区域：/area", description = "地区的增删查改")
@RestController
@RequestMapping(value = "area", produces = {"application/json;charset=UTF-8"})
@ApiResponses(value = {
        @ApiResponse(code = 400, message = "系统异常", response = RedisService.class),
        @ApiResponse(code = 401, message = "测试异常", response = AreaMapper.class)
})
public class AreaController {
    ...
}

显示效果

[@ApiOperation]

@ ApiOperation用于在API资源中声明单个操作。 操作被认为是路径和HTTP方法的唯一组合。 只扫描使用@ ApiOperation注释的方法并添加API声明。

注释将影响Swagger输出的两个部分，[API对象]，每个路径将创建一个，以及[操作对象]，将根据@ApiOperation创建一个。 请记住，在使用Servlet时，@ Api会在设置路径时影响API对象。

JAX-RS的用法是

    @ApiOperation(value = "根据areaId获取地区", notes = "根据url的id来获取地区")
    @RequestMapping(value = " {areaId}", method = RequestMethod.GET)
    public Map<String, Object> getArea(@PathVariable("areaId") Integer areaId) {
        ...
    }

使用效果

[@ApiResponses], [@ApiResponse]

使用HTTP状态代码返回错误（或其他成功消息）是一种常见做法。 虽然操作的常规返回类型在[@ApiOperation]中定义，但应使用这些注释描述其余的返回代码。

@ ApiResponse描述了具体的可能响应。 它不能直接在方法上使用，需要包含在@ ApiResponses的数组值中（无论是否有一个响应或更多）。

如果响应伴随身体，也可以描述身体模型（每个响应一个模型）。

用法（JAX-RS，Servlet或其他）之间的使用没有区别：

    @RequestMapping(value = " {areaId}", method = RequestMethod.GET)
    @ApiResponses(value = {
            @ApiResponse(code = 400, message = "系统异常", response = RedisService.class),
            @ApiResponse(code = 401, message = "测试异常", response = AreaMapper.class)
    })
    public Map<String, Object> getArea(@PathVariable("areaId") Integer areaId) {
         ...
    }

有关此注释，用法和边缘情况的更多详细信息，请查看javadoc ([@ApiResponses], [@ApiResponse]**.

[@ApiParam]

@ ApiParam仅用于JAX-RS参数注释（@PathParam，@ QueryParam，@HeaderParam，@ FormParam和JAX-RS 2，@ BeanParam）。 虽然swagger-core默认扫描这些注释，但@ ApiParam可用于添加有关参数的更多详细信息，或在从代码中读取时更改值。

在Swagger规范中，这转换为[参数对象]。

Swagger将获取这些注释的value（）并将它们用作参数名称，并根据注释设置参数类型。 对于body参数（JAX-RS方法的单个输入参数），名称将自动设置为body（根据Swagger规范的要求）。

如果存在，Swagger还将使用@ DefaultValue的值作为默认值属性。

    @RequestMapping(method = RequestMethod.POST)
    public Map<String, Object> addArea(
           @ApiParam(value = "地区名称",required = true) String areaName,
           @ApiParam(value = "地区domain",required = true) @RequestBody  Area area) {
           ...
    }

这里我们有两个参数。 第一个是areaName，它是路径的一部分。 第二个是正文，在本例中是一个Area对象。 请注意，两个参数都将required属性设置为true。 对于@PathParam，这是多余的，因为默认情况下它是强制性的，不能被覆盖。

输出将是:

有关此注释，用法和边缘情况的更多详细信息，请查看 javadocs.

[@ApiImplicitParam], [@ApiImplicitParams]

您可能希望手动描述操作参数。 这可能有多种原因，例如：

• 使用不使用JAX-RS注释的Servlet.
• 想要隐藏定义的参数，并使用完全不同的定义覆盖它.
• 描述在到达JAX-RS实现之前过滤器或其他资源使用的参数.

由于可以包含几个参数，@ ApiImplicitParams允许多个@ ApiImplicitParam定义。

在Swagger规范中，这些转换为[Parameter Object]。

在隐式定义参数时，为Swagger的定义设置name，dataType和paramType是很重要的。

 @ApiImplicitParams({
            @ApiImplicitParam(name = "areaName", value = "地区名称", required = true, dataType = "string", paramType = "query"),
            @ApiImplicitParam(name = "priority", value = "地区编号", required = false, dataType = "string", paramType = "query"),
            @ApiImplicitParam(name = "id", value = "地区id", required = true, dataType = "long", paramType = "query")
    })
    @RequestMapping(value = "editArea", method = RequestMethod.POST)
    public Map<String, Object> editArea(Area area) {
        ...
    }

在上面的示例中，我们可以看到具有多个参数的Servlet定义。 dataType可以是基元名称或类名称。 paramType可以是Swagger支持的任何参数类型（有关更多详细信息，请参阅javadoc或规范）.

有关此注释，用法和边缘情况的更多详细信息，请查看javadoc (@ApiImplicitParam, @ApiImplicitParams).

[@ApiModel]

Swagger-core在整个API内省中基于对它们的引用构建模型定义。 @ ApiModel允许您操作模型的元数据，从简单的描述或名称更改到多态的定义。

这转换为Swagger规范中的[Model Object]。

在其基本功能中，您可以使用@ ApiModel来更改模型的名称并为其添加描述：

@ApiModel(value = "区域domain",description = "区域的数据库模型")
public class Area {
     ...

}

我们将模型的名称从Area更改为区域domain

为了支持多态和继承，我们使用discriminator和subTypes字段。 两者都必须用于Swagger输出才有效。

“discriminator”字段必须是顶部模型中的字段，该字段将用于确定正在使用哪个子模型。 例如，如果您有一个Animal类，其中Cat，Dog和Chicken作为子类，则animalType字段可以用作鉴别器来确定实际使用的是哪种动物。

subTypes必须列出继承模型的类。 类本身不必从超类型继承。 事实上，Swagger不会自动读取扩展类，你必须在subTypes中手动描述这些类，以便对它们进行解析。

@ApiModel(value="SuperModel", discriminator = "foo", subTypes = {SubModel.class})
public class SuperModel {...}

@ApiModel(value="SubModel")
public class SubModel {...}

上面的代码片段是一个如何描述继承的简单示例。 注意SubModel不会扩展SuperModel。 以同样的方式，您可以添加多个继承类。 可以有任意数量的继承级别

For further details about this annotation, usage and edge cases, check out the javadocs.

[@ApiModelProperty]

虽然swagger-core将内省字段和setter / getter，但它也会读取和处理JAXB注释。 @ ApiModelProperty允许控制Swagger特定的定义，例如允许的值和附加注释。 如果您想在某些情况下隐藏属性，它还提供其他过滤属性。

有关Swagger Spec中的相关信息，请查看Property Object.

public class Area {
    @ApiModelProperty(value = "区域id", required = true, position = 1, example = "1")
    private Integer areaId;

    @ApiModelProperty(value = "区域名称", required = true, position = 2, example = "北京")
    private String areaName;

    @ApiModelProperty(value = "区域编号", required = true, position = 3, example = "10001")
    private Integer priority;

    @ApiModelProperty(value = "添加时间", required = false, position = 4, example = "2017-02-02")
    private Date createTime;

    @ApiModelProperty(value = "最后修改时间", required = false, position = 5, example = "2017-02-02")
    private Date lastEditTime;

}

这是向模型属性添加简短描述的简单示例。 还可以观察到，虽然status是一个String，但我们将其记录为只有三个可能的值。

有关此注释，用法和边缘情况的更多详细信息，请查看javadocs.

Name	Description
@Api	将类标记为Swagger资源.
@ApiImplicitParam	表示API操作中的单个参数。
@ApiImplicitParams	一个包装器，允许列出多个ApiImplicitParam对象。
@ApiModel	提供有关Swagger模型的其他信息。
@ApiModelProperty	添加和操作模型属性的数据.
@ApiOperation	描述针对特定路径的操作或通常是HTTP方法.
@ApiParam	鈥为操作参数添加其他元数据.
@ApiResponse	描述操作的可能响应.
@ApiResponses	鈥一个包装器，允许列出多个ApiResponse对象.
@Authorization	鈥声明要在资源或操作上使用的授权方案.
@AuthorizationScope	鈥描述OAuth2授权范围.