Hi
I’m designing an API that has a categories endpoint that returns an array of categories. In the definition of the category is an array of categories, i.e. subcategories.
Our data has 3 levels of categories.
How do I:
a) model this properly in OAS 3.0 ? I want to have a parameter of the category level (so I can just get level 2 for example) and I want to be able to pass in an array of categories to get their subcategories.
b) how do I provide examples of categories, subcategories and subsubcategories?
Here is how I’ve done it:
Model: “Category”:
{
"title": "Category",
"type": "object",
"x-examples": {
"TestCategory": {
"name": "Test",
"description": "All Tests",
"subcategories": [
"$ref(#/components/schemas/Category)"
]
},
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"subcategories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Category"
}
}
}
}
endpoint: “/categories”:
{
"get": {
"summary": "Gets categories",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Category"
}
}
}
}
}
},
"parameters": [
{
"schema": {
"type": "array"
},
"in": "query",
"name": "categories"
},
{
"schema": {
"type": "integer"
},
"in": "query",
"name": "categoryLevel"
}
],
"description": "Gets categories",
"operationId": "getCategories",
"tags": []
}
}