第十二章 使用中的 OpenAPI 属性

本附录列出了 API 管理工具在生成 REST 服务类时使用的 OpenAPI 2.0 规范的属性。此处未列出的属性将被忽略。有几个扩展属性;它们的名称以 x-ISC 开头。

Swagger

  • basePath

  • consumes

  • host

  • produces

  • definitions (请注意,API 管理工具在生成代码时不使用 Schema 对象的任何属性)

  • parameters (for details, see “Parameter Object”)

  • paths (for details, see “Path Item Object”)

  • info (for details, see “Info Object”)

  • swagger (must be “2.0”)

有关这些属性的详细信息,请参阅 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object。

Info Object

  • title

  • description

  • x-ISC_RequiredResource (访问 REST 服务的任何端点所需的已定义资源及其访问模式 (resource:mode) 的逗号分隔列表)

  • version

有关标准属性的详细信息,请参阅 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object。

Path Item Object

  • $ref

  • get, put, and so on (支持 OpenAPI 2.0 规范中列出的所有方法)

请注意,对于 options 方法, 不会生成存根方法供实现。相反,%CSP.REST 类会自动执行所有选项处理。

  • parameters (for details, see “Parameter Object”)

有关标准属性的详细信息,请参阅 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#pathItemObject.

Operation Object

  • operationId

  • summary

  • description

  • consumes

  • produces

  • parameters (for details, see “Parameter Object”)

  • x-ISC_CORS (一个标志,指示应支持对此端点/方法组合的 CORS 请求)

  • x-ISC_RequiredResource (访问 REST 服务的此端点所需的已定义资源及其访问模式 (resource:mode) 的逗号分隔列表)

  • x-ISC_ServiceMethod (在后端调用以服务此操作的类方法的名称;默认是 operationId,通常是合适的)

  • responses (请注意,在响应对象中,状态可能是 HTTP 状态代码或“默认”)

有关标准属性的详细信息,请参阅 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operationObject。

Parameter Object

  • name

  • in

  • description

  • required

  • $ref

  • type (cannot be “formData”; other types are permitted)

  • format

  • allowEmptyValue

  • maxLength

  • minLength

  • pattern

  • maximum

  • minimum

  • exclusiveMaximum

  • exclusiveMinimum

  • multipleOf

  • collectionFormat

  • minItems

  • maxItems

  • uniqueItems

  • items (for details, see “Items Object”)

有关这些属性的详细信息,请参阅 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameter-object。

Items Object

  • type

  • format

  • allowEmptyValue

  • maxLength

  • minLength

  • pattern

  • maximum

  • minimum

  • exclusiveMaximum

  • exclusiveMinimum

  • multipleOf

  • collectionFormat

  • minItems

  • maxItems

  • uniqueItems

有关这些属性的详细信息,请参阅 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#items-object。

Logo

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

更多推荐