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 或其他）之间的使用没有区别：


    @ApiOperation(value = "根据areaId获取地区", notes = "根据url的id来获取地区")
    @ApiImplicitParam(value = "地区id", name = "areaId", required = true, dataType = "int", paramType = "path", defaultValue = "1", example = "1")
    @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.


@ApiModel(value = "区域domain",description = "区域的数据库模型")
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授权范围.

Swagger 注解传参

[@Api]

[@ApiOperation]

[@ApiResponses], [@ApiResponse]

[@ApiParam]

[@ApiImplicitParam], [@ApiImplicitParams]

[@ApiModel]

[@ApiModelProperty]

相关帖子

Swagger2+Oauth2 导致无法访问页面无法请求

spring boot 项目集成 knife4j 2.0.5 并实现入参分组校验显示

SPRING CLOUD GATEWAY 集成 SWAGGER 方案总结 (请求路径中带有 ",")

swagger2 返回值 Map,Json，实体类部分字段注释描述信息说明

Swagger2.X 注解

Swagger 初体验

前后端分离时如何优雅的编写 API 文档

欢迎来到这里！

Swagger 注解 传参

[@Api]

[@ApiOperation]

[@ApiResponses], [@ApiResponse]

[@ApiParam]

[@ApiImplicitParam], [@ApiImplicitParams]

[@ApiModel]

[@ApiModelProperty]

相关帖子

Swagger2+Oauth2 导致无法访问页面无法请求

spring boot 项目集成 knife4j 2.0.5 并实现入参分组校验显示

SPRING CLOUD GATEWAY 集成 SWAGGER 方案总结 (请求路径中带有 ",")

swagger2 返回值 Map,Json，实体类部分字段注释描述信息说明

Swagger2.X 注解

Swagger 初体验

前后端分离时如何优雅的编写 API 文档

欢迎来到这里！

Swagger 注解传参