swagger-api / swagger-api/swagger-ui

OpenApi 3.1 Data Type support

Open
#10,501 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Content & configuration

Display the data types as previously.
We have a lot of DTOs that may be similar in structure, and different DTOs tailored to each endpoint to improve performance, so missing the data type, specially in arrays makes it difficult to quickly find the DTO as not we need to first find the endpoint and then the response object.
We have the $ref object in the yaml, so the data should be there as previously.

Feel free to point me to an existing issue, I couldn't find if this was already reported.

Swagger/OpenAPI definition:

"requestBody": {
         "content": {
           "application/json": {
             "schema": {
               "$ref": "#/components/schemas/ResaleEventDto"
             }
           }
         },
         "required": true
       }
Is your feature request related to a problem?

Frustrating problem to identify the object type provided.
Reported here:
https://github.com/springdoc/springdoc-openapi/issues/3024
https://github.com/springdoc/springdoc-openapi/issues/2867

Describe the solution you'd like

Add the $ref name to the objects, including arrays.

Describe alternatives you've considered

Reverted to 2.0 as it is more useful.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the provided OpenAPI 3.1 requestBody schema in Swagger UI and compare its rendering with OpenAPI 3.0. Trace the schema and array display paths, using the referenced ResaleEventDto example; the work is done when referenced object names are displayed consistently, including for arrays.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
api, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.