Swagger 继承和组合 [英] Swagger Inheritance and Composition
问题描述
在我的简化"API 中，所有响应都是从基本响应"类派生(继承).响应类由一个充满元数据的头部和包含用户请求的核心数据的主体组成.响应(在 JSON 中)的布局使得所有元数据都在第一个层"上，而正文是一个称为正文"的单个属性，因此
响应|--元数据属性 1 (string/int/object)|--元数据属性 2 (string/int/object)|--body(对象)|--body 属性 1 (string/int/object)|--body 属性 2 (string/int/object)我尝试使用以下 JSON 大摇大摆地定义这种关系:
<代码>{...定义":{回复": {所有的": [{"$ref": "#/definitions/response_header"},{特性": {身体": {"description": "响应的正文(不是元数据)",架构":{"$ref": "#/definitions/response_body"}}}}]},响应头":{类型":对象"，必需的": [结果"],特性": {结果": {类型":字符串"，"description": "'success' 的值，对于成功的响应，或 'error' 如果有错误",枚举":[错误"，成功"]},信息": {类型":字符串"，"description": "如果出现问题，一个合适的错误信息."}}},response_body":{类型":对象"}}}然后我尝试通过创建从 body/header 继承的各种 body/header 类来创建不同的响应，然后创建由相关 header/body 类组成的子响应类(显示在底部的源代码中).但是，我确信这要么是错误的做事方式，要么是我的实现不正确.我一直无法在 关于多态性和组合很容易理解，因为它缺乏示例.当我在网上搜索时，有很多很好的例子在 extends有效.
对于 swagger 2.0 我在 通过这个 google group 在 github 上 swagger 规范源
基于上述来源，这里是一个简短的有效继承示例在 YAML 中:
定义:宠物:鉴别器:petType必需的:- 姓名- petType # 需要继承才能工作特性:姓名:类型:字符串宠物类型:类型:字符串猫:所有的:- $ref: '#/definitions/Pet' # 猫拥有宠物的所有属性- 属性:# 仅适用于猫的额外属性狩猎技能:类型:字符串默认值:懒惰枚举:- 懒惰的- 挑衅的狗:所有的:- $ref: '#/definitions/Pet' # 狗拥有宠物的所有属性- 属性:# 仅适用于狗的额外属性包装尺寸:描述:狗来自的包的大小类型:整数In my "simplified" API, all responses are derived (inherit) from a base "response" class. The response class is composed of a header filled with metadata, and the body which contains the core data the the user is requesting. The response (in JSON) is laid out such that all the metadata is on the first "layer" and the body is a single attribute called "body" as such
response
|--metadata attribute 1 (string/int/object)
|--metadata attribute 2 (string/int/object)
|--body (object)
|--body attribute 1 (string/int/object)
|--body attribute 2 (string/int/object)
I have tried to define this relationship in swagger with the following JSON:
{
...
"definitions": {
"response": {
"allOf": [
{
"$ref": "#/definitions/response_header"
},
{
"properties": {
"body": {
"description": "The body of the response (not metadata)",
"schema": {
"$ref": "#/definitions/response_body"
}
}
}
}
]
},
"response_header": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string",
"description": "value of 'success', for a successful response, or 'error' if there is an error",
"enum": [
"error",
"success"
]
},
"message": {
"type": "string",
"description": "A suitable error message if something went wrong."
}
}
},
"response_body": {
"type": "object"
}
}
}
I then try to create different responses by creating the various body/header classes that inherit from body/header, and then create child response classes that are composed of the relevant header/body classes (shown in source code at bottom). However, I am certain that either this is the wrong way to do things, or that my implementation is incorrect. I have been unable to find an example of inheritance in the swagger 2.0 specification (shown below) but have found an example of composition.
I am pretty certain that this "discriminator" has a large part to play, but not sure what I need to do.
Question
Could someone show me how one is supposed to implement composition+inheritance in swagger 2.0 (JSON), preferably by "fixing" my example code below. It would also be great if I could specify an ErrorResponse class that inherits from response where the "result" attribute in the header is always set to "error".
{
"swagger": "2.0",
"info": {
"title": "Test API",
"description": "Request data from the system.",
"version": "1.0.0"
},
"host": "xxx.xxx.com",
"schemes": [
"https"
],
"basePath": "/",
"produces": [
"application/json"
],
"paths": {
"/request_filename": {
"post": {
"summary": "Request Filename",
"description": "Generates an appropriate filename for a given data request.",
"responses": {
"200": {
"description": "A JSON response with the generated filename",
"schema": {
"$ref": "#/definitions/filename_response"
}
}
}
}
}
},
"definitions": {
"response": {
"allOf": [
{
"$ref": "#/definitions/response_header"
},
{
"properties": {
"body": {
"description": "The body of the response (not metadata)",
"schema": {
"$ref": "#/definitions/response_body"
}
}
}
}
]
},
"response_header": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string",
"description": "value of 'success', for a successful response, or 'error' if there is an error",
"enum": [
"error",
"success"
]
},
"message": {
"type": "string",
"description": "A suitable error message if something went wrong."
}
}
},
"response_body": {
"type": "object"
},
"filename_response": {
"extends": "response",
"allOf": [
{
"$ref": "#definitions/response_header"
},
{
"properties": {
"body": {
"schema": {
"$ref": "#definitions/filename_response_body"
}
}
}
}
]
},
"filename_response_body": {
"extends": "#/definitions/response_body",
"properties": {
"filename": {
"type": "string",
"description": "The automatically generated filename"
}
}
}
}
}
Diagram Update
To try and clarify what I want, I have created the very basic diagram below which aims to show that all responses are instantiations of the "response" object that have been built by (composition) using any combination of response_header and response_body objects. The response_header and response_body objects can be extended and inserted into any response object, which is done in the case of a filename_response which uses the filename_response_body child of the base response_body class. Both error and successful responses use the "response" object.
As a beginner in swagger I don't find the official documentation about polimorphism and composition easy to undestand, because it lacks an example. When I searched the net, there are lots of good examples refering to swagger 1.2 when extends was valid.
For swagger 2.0 I found a good example in swagger spec sources on github via this google group
Based on above sources, here is a short valid inheritance example in YAML:
definitions:
Pet:
discriminator: petType
required:
- name
- petType # required for inheritance to work
properties:
name:
type: string
petType:
type: string
Cat:
allOf:
- $ref: '#/definitions/Pet' # Cat has all properties of a Pet
- properties: # extra properties only for cats
huntingSkill:
type: string
default: lazy
enum:
- lazy
- aggressive
Dog:
allOf:
- $ref: '#/definitions/Pet' # Dog has all properties of a Pet
- properties: # extra properties only for dogs
packSize:
description: The size of the pack the dog is from
type: integer
这篇关于Swagger 继承和组合的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
