[@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 {

...

}

_20180814171413png

[@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) {

...

}

imagepng

[@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]**.

imagepng

[@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.

imagepng

[@ApiImplicitParam], [@ApiImplicitParams]

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

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

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

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

在隐式定义参数时,为Swagger的定义设置namedataTypeparamType是很重要的。​​​​​​​

@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或规范).

imagepng

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

[@ApiModel]

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

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

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

@ApiModel(value = “区域domain”,description = “区域的数据库模型”)

public class Area {

…


}

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

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

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

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

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

public class SuperModel {...}


@ApiModel(value="SubModel")

public class SubModel {...}

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

imagepng

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,但我们将其记录为只有三个可能的值。

imagepng

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

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

权威|前沿|技术|干货|国内首个API全生命周期开发者社区

更多推荐