title: Swagger Inheritance and Composition
body: <p>In my "simplified" API, all responses are derived (<em>inherit</em>) from a base "response" class. The response class is <em>composed</em> 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</p>
  
  <pre><code>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)
  </code></pre>
  
  <p>I have tried to define this relationship in swagger with the following JSON:</p>
  
  <pre><code>{
      ...
      "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"
          }
      }
  }
  </code></pre>
  
  <p>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 <a href="https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md">swagger 2.0 specification</a> (shown below) but have found an example of <a href="https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/models/modelWithComposition.json">composition</a>.</p>
  
  <p><img src="https://i.stack.imgur.com/zPJN4.png" alt="enter image description here"></p>
  
  <p>I am pretty certain that this "discriminator" has a large part to play, but not sure what I need to do. </p>
  
  <h2>Question</h2>
  
  <p>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".</p>
  
  <pre><code>{
      "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"
                  }
              }
          }
      }
  }
  </code></pre>
  
  <h3>Diagram Update</h3>
  
  <p>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.</p>
  
  <p><img src="https://i.stack.imgur.com/gqQUQ.png" alt="enter image description here"></p>