第十二章 使用中的 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。