Swagger Inheritance and Composition

swagger

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.

enter image description here

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.

enter image description here

Best Answer

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

Related Solutions

Json – Swagger UI 2.1 Stuck “fetching resource list”

I've tested your spec, and while I'm not getting the same error you do, the spec is indeed invalid.

If you look at #/definitions/MatchData/properties/stats, you'll see that you define the type: array but you don't provide an 'items' property next to it to say which array it is (and that's mandatory). You may have intended to use type: integer like the properties above it, which goes along with the format: int64.

Since I don't know what you intended to provide, it's difficult to give an accurate solution, but if you add a comment with what you intended to do, I could provide a more detailed answer.

Upon some additional testing, I discovered that there's a bug in the UI. After you make that modification and the spec loads, the operation itself will not expand unless you click on the Expand Operations link. I've opened an issue about it, feel free to follow it there.

Swagger – Specify Optional Object Property or Multiple Responses

You're getting the error in the model, because that's not the way to define required properties.

The correct form would be:

    "my_response_object": {
        "type": "object",
        "required": [ "result" ],
        "properties": {
            "result": {
                "type": "string",
                "description": "value of 'success' or 'error', indicated whether was successful"
            },
            "message": {
                "type": "string",
                "description": "an error message if there was an issue"
            },
            "filename": {
                "type": "string",
                "description": "the filename to return if the request was successful"
            }
        }
    }

Anything not in the required property is assumed to be optional. Keep in mind that this implies that it's possible to get both message and filename.

You can then use this model for your 200 response.

However - when it comes to REST API design, this breaks one of the more common standards. The status codes, taken from the HTTP protocol are meant to convey the outcome of the operation. 2XX are used for successful responses, 4XX are for errors due to bad user input, 5XX are for problems on the server side (3XX are for redirects). What you're doing here, is tell the client - the operation was successful, but in fact, it can be an error.

If you can still modify the API, I'd highly recommend making that distinction using the status codes, even using the fine tuned distinctions such as 200 for a successful GET operation, 201 for successful POST (or creation) operation and so on, based on the definitions here - http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.