Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OpenAPI 3.1 compatibility: "examples" property not allowed / "type" property as an array not allowed #431

Open
Tithugues opened this issue Apr 26, 2024 · 2 comments
Assignees
Labels

Comments

@Tithugues
Copy link

Describe the bug
From OpenAPI 3.1, the example property is deprecated and examples is preferred and type property can be a string, but also an array of strings.

The examples property and the type as an array seem not to be supported.

To Reproduce

  1. Create a YAML file in a project
  2. Copy the following lines in the file:
openapi: '3.1.0'
info:
  version: '0.0.1'
  title: 'My API'
paths:
  /my/route:
    get:
      operationId: MyRoute
      responses:
        200:
          description: 'Successful response.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  a_property:
                    type: ['string', 'null']
                    examples:
                      - null
                      - "Hello world!"
  1. See errors

Expected behavior
I would expect examples and type as an array to be allowed in the editor part.

Screenshots
Editor complains about those 2 properties:
image

On the other hand, the preview seems to "understand" the syntax:
image

Stack trace
No exception.

Desktop (please complete the following information):

  • Zalando OpenAPI Editor version: 1.3.0
  • IDEA version: PhpStorm 2024.1.1 (Build #PS-241.15989.102, built on April 23, 2024)
  • Java version: OpenJDK 64-Bit Server VM by JetBrains s.r.o.
  • Operating System & version: Ubuntu 22.04

Additional context
Swagger editor (https://editor-next.swagger.io) does not complain about this YAML file.


Am I wrong anywhere?
Is the OpenAPI 3.1 not supported? If so, is it expected to be supported?

Thank you! 🙏

@Tithugues Tithugues added the bug label Apr 26, 2024
@Tithugues
Copy link
Author

Regarding the examples, it seems it can't be used everywhere! Sorry for this mistake. 🙏

On the other hand, regarding the type type, I'm not sure I made a mistake.

@tmack8001
Copy link

tmack8001 commented Oct 10, 2024

examples should be supported on a number of types.

  • Parameters: You can provide examples for parameters to illustrate how they should be used.
  • Request Bodies: Examples can be included to demonstrate the expected content of request bodies.
  • Responses: You can define examples for responses to show what the response might look like.
  • Components: Within the components section, you can define reusable examples for schemas, request bodies, and responses.

I have been wanting to add examples to properties of a type: object entity for example for properties that are of type string, number, or similar.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

4 participants