"lint" command incorrectly flags "examples:" with an error when structured as an object
kdipippo opened this issue · 4 comments
Describe the bug
OpenAPI 3.1.0 specifies examples: as an object where properties are exampleNames with their own object structure. "- summary:" is not found in this documentation page. Also in Swagger's latest documentation, this field is an object.
However, the linting command returns the message "Expected type array but got object." for this object.
To Reproduce
Small spec to replicate bug:
openapi.yaml
openapi: 3.1.0
info:
description: Example API spec
version: v1
title: Example API
contact:
name: Example Team
email: example@example-team.com
url: https://www.example-team.com/
license:
name: Example License
url: https://www.example-license.com/
tags:
- name: ExampleCall
description: Example call
servers:
- url: https://example-server.com:1234
paths:
/api/v1/example-call:
$ref: example-call.yaml
components:
securitySchemes:
BearerAuth:
type: http
description: Bearer token authentication.
scheme: bearer
example-call.yaml
get:
summary: Perform example call
description: Example call for figuring out how to add schema and media-type examples.
security:
- BearerAuth: []
tags:
- ExampleCall
operationId: getExampleCall
parameters:
- name: limit
description: Limit to number of results
in: query
required: false
schema:
type: integer
example: 10
example: 10
responses:
"200":
description: Successfully retrieved simple response objects.
content:
application/json:
schema:
type: object
properties:
Message:
type: string
description: Message response string.
minLength: 1
example: "Results found"
Items:
type: array
description: Array of objects returned.
items:
type: object
properties:
Name:
type: string
description: Name field.
minLength: 1
example: "Example name 1"
example:
Name: "Example name 1"
example:
- Name: "Example name 1"
- Name: "Example name 2"
Count:
type:
- string
- "null"
description: Count of objects returned, null if error occured.
example: ""
examples:
apiReturnedItems:
summary: API returned items found.
value:
Message: "Results found"
Items:
- Name: "Example name 1"
- Name: "Example name 2"
Count: "2"
apiReturnedEmpty:
summary: API returned empty results.
value:
Message: "No results found"
Items: []
Count: "0"
"500":
description: Internal server error encountered.
content:
application/json:
schema:
type: object
properties:
Message:
type: string
description: Message response string.
minLength: 1
example: "Results found"
Items:
type: array
description: Array of objects returned.
items:
type: object
properties:
Name:
type: string
description: Name field.
minLength: 1
example: "Example name 1"
example:
Name: "Example name 1"
example:
- Name: "Example name 1"
- Name: "Example name 2"
Count:
type:
- string
- "null"
description: Count of objects returned, null if error occured.
example: ""
examples:
apiErrorEncountered:
summary: API error encountered.
value:
Message: "API error encountered"
Items: []
Count: nullI have node_modules with redocly-cli 1.10.0 in here. Running the command:
➜ node_modules/@redocly/cli/bin/cli.js lint openapi.yaml --format=stylish
(node:55605) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
No configurations were provided -- using built in recommended configuration by default.
validating openapi.yaml...
example-call.yaml:
54:29 error spec Expected type `array` but got `object`.
103:29 error spec Expected type `array` but got `object`.
18:5 warning operation-4xx-response Operation must have at least one `4XX` response.
openapi.yaml: validated in 14ms
❌ Validation failed with 2 errors and 1 warning.
run `redocly lint --generate-ignore-file` to add all problems to the ignore file.
The lines 54 and 103 are both referring to the examples:
examples:
apiReturnedItems:
summary: API returned items found.
value: ...
apiReturnedEmpty:
summary: API returned empty results.
value: ...
Expected behavior
redocly/cli flags this issue as an error when this is the documented structure. Expected behavior is to not see an error.
Logs
N/A
OpenAPI description
OpenAPI 3.1.0
Redocly Version(s)
"@redocly/cli": "^1.10.0"
Node.js Version(s)
➜ npm --version
10.4.0
➜ node --version
v21.6.1
Hi @kdipippo, your indentation is wrong. The examples keywords on lines 53 and 102 should have the same indentation as the corresponding schemas. Hope this helps.
@tatomyr ah! Thanks for the correction! I'm trying to wrap my head around how to pepper these examples. In the response format:
"200":
content:
application/json:
schema:
examples:examples: is at the same indent as schema:. Does schema: also allow for its own example inside? i.e.
"200":
content:
application/json:
schema:
type: object
properties:
example: # <---
examples:Or is "schema" in here a different "schema" than what exists elsewhere? Media Type object lists that it itself has examples while the schema object inside the Media Type object also has example, but maybe the latter is deprecated in favor of the examples array on the outer object.
You can define an example inside a schema. And yes, I believe that it's deprecated in favour of the outer examples (not an array but an object, though).