Overwriting description of referenced objects not possible (openAPI 3.1)

[elnipa]

According to openAPI 3.1 specification it is possible now to overwrite descriptions and summary where objects are referenced:
When using the Reference Object, summary and description fields can now be overridden.
https://github.com/OAI/OpenAPI-Specification/releases

e.g.

paths:
  /items:
    post:
      parameters:
        - $ref: '#/components/parameters/item'
          description: The specific item in question

RapiDoc seems to render the description from the referenced object only.
We use this quite heavily to re-use models and change some description details in the specific context.

Would love to see the that part of openAPI 3.1 spec implemented in the future. :-)

[philsturgeon]

Hello! As the maintainer of openapi.tools, and as somebody works with Linux Foundation helping out in OpenAPI-land, I'm reaching out to tooling vendors to track the progress towards supporting OpenAPI v3.1, to see what roadblocks there are beyond folks just generally being busy at this ridiculous time.

OpenAPI v3.1 has a bunch of great little changes, solving problems like the the JSON Schema <!=> OpenAPI Schema Object divergence. It also fixes some other inconsistencies and duplicate ways of doing things. It's the best version and everyone should be using it, but we need tooling to catch up. Just in case folks didn't notice, or don't have resources to simplify the process, I'm here to give a friendly prod and send over some handy links.

Here are a few articles showing off the differences between OpenAPI v3.0 and v3.1.

• https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
• https://www.apimatic.io/blog/2021/09/migrating-to-and-from-openapi-3-1/
• https://nordicapis.com/whats-new-in-openapi-3-1-0/

Here are some example files which can make for handy pass/fail test cases:

https://github.com/Mermade/openapi3-examples/tree/master/3.1

If you're looking for the JSON Schema that defines a valid OpenAPI document, that'll be right over here:

https://github.com/OAI/OpenAPI-Specification/tree/main/schemas/v3.1

No rush, but when you're starting work on it, please update this issue so I can update openapi.tools to reflect that, and folks will have a way to subscribe for updates.

LMK if you have any questions!

[lucianojs]

I have a same problem.

Current Behavior

When I use this sample specification:

openapi: 3.1.0
info:
  version: 1.0.0
  title: Example.com
  termsOfService: 'https://example.com/terms/'
  contact:
    email: contact@example.com
    url: 'http://example.com/contact'
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  description: |
    This is an **example** API to demonstrate features of the OpenAPI
    specification.
servers:
  - url: 'https://example.com/api/v1'
paths:
  '/users':
    post:
      summary: user
      description: User.
      operationId: createUser
      responses:
        '200':
          description: OK
      requestBody:
        description: Updated user object
        content:
          application/json:
            schema:
              description: Names and Numbers (specific)
              $ref: '#/components/schemas/NamesAndNumbers'
        required: true
components:
  schemas:
    Name:
      type: string
      description: Generic Name.
    Number:
      type: integer
    Names:
      type: object
      description: names description
      properties:
        oneName:
          $ref: "#/components/schemas/Name"
          description: One name (specific).
        otherName:
          $ref: "#/components/schemas/Name"
          description: Other name (specific).
    Numbers:
      type: object
      description: numbers description
      properties: 
        oneNumber:
          $ref: "#/components/schemas/Number"
          description: One number (specific)
        otherNumber:
          $ref: "#/components/schemas/Number"
          description: Other number (specific)
    NamesAndNumbers:
      type: object
      description: names and numbers description
      properties: 
        names: 
          $ref: "#/components/schemas/Names"
        numbers:
          $ref: "#/components/schemas/Numbers"

this tool show this:

Expected Behavior

I expected it to show the specific descriptions.

[mrin9]

we depend on swagger parser for parsing the spec per the specification. and therefore don't have much of room to deal with it on our end. will keep this issue open for tracking

[lucianojs]

we depend on swagger parser for parsing the spec per the specification. and therefore don't have much of room to deal with it on our end. will keep this issue open for tracking

I believe you can evaluate replace with this component: APIDevTools/json-schema-ref-parser

This was done at Authress-Engineering/openapi-explorer#57

[mrin9]

Thanks fo the suggestion, we do keep testing the spec parsers time to time, we also keep an eye on their issue list and release notes

APIDevTools/json-schema-ref-parser is promising one but
so far we found swagger parser to be working as expected for most of the spec. their parsing performance is also better and provide ability to partially parse the spec.

our assessment of switching the parser in order to take care of this issue is too risky at the moment

[tib-c]

Since december 2022 the features were added to swagger parser as you can see here. I would appreciate if this issue could be realized soon then. Overwriting properties of referenced schemas is such a powerful extension, we can't wait to use it!

Thank you :)

[adamsussman]

Pinging this issue since it appears that the underlying library support has been available for a while. We really need this feature and will have to move to another tool if it can't be done.

[iaforek]

Soon there will be two years anniversary since the issue was opened.

[mrin9]

its fixed in v9.3.6
for test case refer to https://rapidocweb.com/examples/override-descriptions-from-refs.html

[tib-c]

In your test case, you use a component from the "schema" section and override the description of that schema.

Did you consider other types of components too, as there is no test case for overriding the descriptions of request bodies or responses? @mrin9
That was the requirement I added here.

Did you consider the "summary" property too, as it can be overridden as well as "description"?

Update: Description works for responses too :)

[toyota790]

Hi @mrin9 ,

I noticed that the overwriting description feature is not working in versions v9.3.7 and v9.3.8, but it works fine in v9.3.6. I am not sure if any new changes have caused this issue. Could you please help check on this? Thank you!