Open API include a component inside another in paths

Question

I think the title of my question is not very explicit, so I will try to explain it better here.

I am currently writing my API documentation with the OpenAPI 3 specification and I have a little problem.

I created two components "Units" and "MeasuresTypes". One of the methods in my API is to retrieve units and the other is to retrieve measurement types. The first allows to return the component "Units" and the second "MeasuresTypes" which also contains the component "Units".

My problem is that I can't find how I can integrate the "Units" component in "MeasuresTypes" in the "measurestypes" path.

Here is an extract from my json file :

{
  "openapi" : "3.0.0",
  "servers" : [ {
    "url" : "https://example.com/api/"
  } ],
  "info" : {
    "version" : "0.0.3",
    "title" : "API PassCare Bêta",
    "description" : "API PassCare en version bêta (Dernière mise à jour le 09/07/2018)"
  },
  "paths" : {
    "/measuresunits?accesstoken={accesstoken}" : {
      "get" : {
        "summary" : "Récupération de la liste des unités de mesures (hors posologie)",
        "description" : "Cette méthode permet de récupérer les unités de mesures qui seront utilisées ",
        "parameters" : [ {
          "name" : "accesstoken",
          "in" : "path",
          "required" : true,
          "description" : "Token d'accès obtenu via 'Obtention du token d'accès'",
          "schema" : {
            "type" : "string"
          }
        }
       ],
        "responses" : {
          "200" : {
            "description" : "Tableau JSON contenant les unités",
            "content" : {
              "application/json" : {
               "schema" : {
                 "type" : "array",
                 "items" : {
                   "type" : "object",
                   "$ref" : "#/components/schemas/Units"
                 }
               }
              }
            }
          }
        }
      }
    },
    "/measurestypes?accesstoken={accesstoken}" : {
      "get" : {
        "summary" : "Récupération de la liste des types de mesures",
        "description" : "Cette méthode permet de récupérer les types de mesures qui peuvent être utilisées dans l'API",
        "parameters" : [ {
          "name" : "accesstoken",
          "in" : "path",
          "required" : true,
          "description" : "Token d'accès obtenu via 'Obtention du token d'accès'",
          "schema" : {
            "type" : "string"
          }
        }
       ],
        "responses" : {
          "200" : {
            "description" : "Tableau JSON contenant les types de mesures",
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "array",
                  "items" : {
                    "type" : "object",
                    "$ref" : "#/components/schemas/MeasuresTypes",
                    //include Units here
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components" : {
    "schemas" : {
      "Patients": {
        "type" : "object",
        "properties" : {
          "firstname" : {
            "type" : "string",
            "description" : "Prénom",
            "example" : "Jean"
          },
          "lastname" : {
            "type" : "string",
            "description" : "Nom",
            "example" : "Dupont"
          },
        }
      },
      "Units": {
        "type" : "object",
        "properties" : {
            "name" : {
              "type" : "string",
              "description" : "Unité",
              "example" : "Cigarette"
            },
            "plural_name" : {
              "type" : "string",
              "description" : "Unité au pluriel",
              "example" : "Cigarettes"
            },
            "api_slug" : {
              "type" : "string",
              "description" : "Slug",
              "example" : "cigarette"
            }
        }
      },
      "MeasuresTypes": {
        "type" : "object",
        "properties" : {
            "name" : {
              "type" : "string",
              "description" : "Nom du type de mesure",
              "example" : "Taille"
            },
            "slug" : {
              "type" : "string",
              "description" : "Slug",
              "example" : "height"
            },
            "round_number" : {
              "type" : "int",
              "description" : "Nombre de chiffres conservés après la virgule",
              "example" : "0"
            }
        }
      }
    }
  }
}

This is the expected response :

[
  {
    "name": "Taille",
    "slug": "height",
    "round_number": "0",
    "unit": {
      "name": "cm",
      "plural_name": "cm",
      "api_slug": "cm"
    }
  }
]

Someone can help me to find a good solution ?

Thanks in advance !

Could you please clarify what you mean by 'and the second "MeasuresTypes" which also contains the component "Units"'? Is `MeasuresTypes` inherited from `Units` (or vice versa)? Or does `MeasureTypes` include `Units` as a property? Does `/measuretypes` return an array that can contain *both* `MeasureTypes` and `Units`? Or does it return an array of *either* `MeasureTypes` or `Units`? Or does it return 2 arrays - one of `MeasureTypes` and another one of `Units`? Or something else? If you post a response example that would also help understand your scenario. — Helen, Jul 10 '18 at 10:57
@Helen `MeasuresTypes` needs to include `Units` in this case. — Thomas Rollet, Jul 10 '18 at 11:05
Possible duplicate of [Property reference to Model on swagger 2.0 (nesting)](https://stackoverflow.com/questions/26287962/property-reference-to-model-on-swagger-2-0-nesting) — Helen, Jul 10 '18 at 11:22
Please see the ^^ linked Q&A. It has an example for OpenAPI 3.0. — Helen, Jul 10 '18 at 11:22
@Helen I don't have the same problem, `MeasuresTypes` will not systematically return `Units` with. I juste need to include `Units` in `MeasuresTypes` for this specific api call — Thomas Rollet, Jul 10 '18 at 11:27

score 0 · Answer 1 · answered Jul 22 '18 at 08:26

You should make use of the allOf keyword in your case. Not tested though:

"responses" : {
  "200" : {
    "description" : "Tableau JSON contenant les types de mesures",
    "content" : {
      "application/json" : {
        "schema" : {
          "type" : "array",
          "items" : {
            "allOf": [
              {
                "$ref" : "#/components/schemas/MeasuresTypes",  
              },
              "type": "object",
              "properties": {
                "unit": {
                  "$ref" : "#/components/schemas/Units"  
                }
              }
            ]
          }
        }
      }
    }
  }
}

Open API include a component inside another in paths

1 Answers1