ruby-on-railsopenapijsonschema
Using $ref to a different Open API 3.0.2 Specification File is throwing error
While I am well versed in the JSON Schema specification I am working to transition to the Open API 3.0.2 specification and I am running into an odd issue trying to DRY up and organize my definitions. I am trying to use $ref to other JSON structures from in nested folders and running into an error. I am sure there is a rule or pathing character I am missing. I should add the $ref under the info block appears to work correctly, it is only the model $ref.
I have been following these guides:
- https://davidgarcia.dev/posts/how-to-split-open-api-spec-into-multiple-files/
- https://spec.openapis.org/oas/v3.0.2
- https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-8-splitting-specification-file/
I am using the committee gem to test these schemas and the error is:
Attempted "$ref": "models/user.json" DRY Extraction to subfolder
{
"type": "object",
"description": "A user account.",
"required": [
"id",
"email"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier for the given record."
},
"email": {
"type": "string",
"description": "The email associated to the given user."
},
"first_name": {
"type": "string",
"description": "User's first name."
},
"last_name": {
"type": "string",
"description": "User's last name."
},
"full_name": {
"type": "string",
"description": "Full user name"
}
}
}
How I have my folder structure setup:
common/
models/
requests/
api.json
The api.json file
{
"openapi": "3.0.2",
"components": {
"schemas": {
"error": {
"properties": {
"code": {
"type": "string",
"description": "Machine readable code for this specific error message."
},
"message": {
"type": "string",
"description": "Description of the error."
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"user": {
"type": "object",
"description": "A user account.",
"required": [
"id",
"email"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier for the given record."
},
"email": {
"type": "string",
"description": "The email associated to the given user."
},
"first_name": {
"type": "string",
"description": "User's first name."
},
"last_name": {
"type": "string",
"description": "User's last name."
},
"full_name": {
"type": "string",
"description": "Full user name"
}
}
},
"user_input": {
"properties": {
"email": {
"type": "string"
},
"first_name": {
"type": "string",
"description": "User's first name."
},
"last_name": {
"type": "string",
"description": "User's last name."
}
},
"required": [
"email"
],
"type": "object"
}
}
},
"info": { "$ref": "common/info.json" },
"paths": {
"/users": {
"get": {
"description": "Returns all the users in the system.",
"operationId": "get--users",
"parameters": [],
"responses": {
"200": {
"description": "[com.test.test]",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "models/user.json"
},
"type": "array"
}
}
},
"headers": {}
}
},
"tags": [
"user"
]
},
"post": {
"description": "Creates a new user.",
"operationId": "post--users",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user_input"
}
}
}
},
"responses": {
"200": {
"description": "com.test.test",
"content": {
"application/json": {
"schema": {
"$ref": "models/user.json"
}
}
},
"headers": {}
},
"409": {
"description": "[com.test.test]",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/error"
},
"type": "array"
}
}
},
"headers": {}
}
},
"tags": [
"user"
]
}
},
"/users/{id}": {
"get": {
"description": "Returns the given user.",
"operationId": "get--users-id",
"parameters": [
{
"deprecated": false,
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"name": "id"
}
],
"responses": {
"200": {
"description": "com.test.test",
"content": {
"application/json": {
"schema": {
"$ref": "models/user.json"
}
}
},
"headers": {}
},
"404": {
"description": "unit",
"content": {
"application/json": {
"schema": {
"type": "integer",
"nullable": true
}
}
},
"headers": {}
}
},
"tags": [
"user"
]
}
}
},
"servers": [
{
"url": "http://bobs.ngrok.io"
}
]
}
Solution
From https://swagger.io/docs/specification/using-ref/
A common misconception is that $ref is allowed anywhere in an OpenAPI specification file. Actually $ref is only allowed in places where the OpenAPI 3.0 Specification explicitly states that the value may be a reference. For example, $ref cannot be used in the info section and directly under paths:
I adjusted my json to..
{
"openapi": "3.0.2",
"components": {
"schemas": {
"error": {
"properties": {
"code": {
"type": "string",
"description": "Machine readable code for this specific error message."
},
"message": {
"type": "string",
"description": "Description of the error."
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"user": { "$ref": "models/user.json#/components/schemas/user" },
"user_input": {
"properties": {
"email": {
"type": "string"
},
"first_name": {
"type": "string",
"description": "User's first name."
},
"last_name": {
"type": "string",
"description": "User's last name."
}
},
"required": [
"email"
],
"type": "object"
}
}
},
"info": {
"contact": {
"name": "Bobs Burgers",
"email": "bob@bobsburgers.com"
},
"description": "Marketplace API.",
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
},
"termsOfService": "",
"title": "explore",
"version": "0.0.2-dev"
},
"paths": {
"/users": {
"get": {
"description": "Returns all the users in the system.",
"operationId": "get--users",
"parameters": [],
"responses": {
"200": {
"description": "[com.test.test]",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/user"
},
"type": "array"
}
}
},
"headers": {}
}
},
"tags": [
"user"
]
},
"post": {
"description": "Creates a new user.",
"operationId": "post--users",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user_input"
}
}
}
},
"responses": {
"200": {
"description": "com.test.test",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user"
}
}
},
"headers": {}
},
"409": {
"description": "[com.test.test]",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/error"
},
"type": "array"
}
}
},
"headers": {}
}
},
"tags": [
"user"
]
}
},
"/users/{id}": {
"get": {
"description": "Returns the given user.",
"operationId": "get--users-id",
"parameters": [
{
"deprecated": false,
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"name": "id"
}
],
"responses": {
"200": {
"description": "com.test.test",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/user"
}
}
},
"headers": {}
},
"404": {
"description": "unit",
"content": {
"application/json": {
"schema": {
"type": "integer",
"nullable": true
}
}
},
"headers": {}
}
},
"tags": [
"user"
]
}
}
},
"servers": [
{
"url": "http://bobs.ngrok.io"
}
]
}
and in the models/user.json file...
{
"components": {
"schemas": {
"user": {
"type": "object",
"description": "A user account.",
"required": [
"id",
"email"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier for the given record."
},
"email": {
"type": "string",
"description": "The email associated to the given user."
},
"first_name": {
"type": "string",
"description": "User's first name."
},
"last_name": {
"type": "string",
"description": "User's last name."
},
"full_name": {
"type": "string",
"description": "Full user name"
}
}
}
}
}
}
The model $ref is supported but apparently has to be nested to work...
"user": { "$ref": "models/user.json#/components/schemas/user" },
- Rcpp Rf_warningcall compiler warnings
- Modify the name of factor variables in lm function(summary function)
- Extreme value analysis and quantile estimation using log Pearson type 3 (Pearson III) distribution - R vs Python
- How to hide NAs when using xlsx::saveWorkbook?
- How do I retrieve a simple numeric value from a named numeric vector in R?
- Matching pair-wise columns from left to right across rows in one dataframe to another dataframe and adding new columns with matching values
- Income to outcome flow chart in Sankey plotly R
- color mapping in geom_conn_bundle not showing correctly
- Print R package startup message AFTER automatic package conflict messages instead of before
- Summing a set of R dataframe rows (column-wise), while retaining the first n columns
- Added variable / partial regression plots for groups in an interaction?
- how to make a topoplot in R with coordinates variable distribution
- List of all functions in base R?
- Plotting multiple plots for different initial conditions in one graph
- Printing repetitively on the same line in R
- Generating UI/Server based on initial selection
- Subset dataframe based on pickerInput
- How to let user pick the data in R-shiny?
- Couldn't show my simple bar charts separately on Shiny R dashboardBody
- How to programmatically filter contents of a second shiny app displayed via iframe
- How to select specific interesting groups for the boxplot in R Shiny app?
- Crosstable and Plot grouping with reactive values
- Is there a way to make multiple Shiny picker inputs where the selections must be disjoint?
- Delay/avoid duplication of shiny server side functions until after credentials
- Predictions only returns value "1"
- How to display a busy indicator in a shiny app?
- Append doesn't work when writing to CSV in R
- Changing the start date of a gantt chart in DiagrammeR
- Check for installed packages before running install.packages()
- Compare two columns element-wise