swagger-api / swagger-api/swagger-parser

Parser ignore the description if it's a $ref

Open
#1,091 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
867
Forks
560
Avg merge
2d 21h
Merged PRs (30d)
7

Description

As said in the title, latest stable release ignores the description if it's a $ref.
It looks like a regression to me because it was working properly a few versions back (can't be sure when, I found at using a code generator).

[main] INFO  o.o.codegen.DefaultCodegen - debugging Cateogry: class Schema {
    type: null
    format: null
    $ref: #/components/schemas/Category
    description: null
    title: null
    multipleOf: null
    maximum: null
    exclusiveMaximum: null
    minimum: null
    exclusiveMinimum: null
    maxLength: null
    minLength: null
    pattern: null
    maxItems: null
    minItems: null
    uniqueItems: null
    maxProperties: null
    minProperties: null
    required: null
    not: null
    properties: null
    additionalProperties: null
    nullable: null
    readOnly: null
    writeOnly: null
    example: null
    externalDocs: null
    deprecated: null
    discriminator: null
    xml: null
}

description is null even though I put down something as follows:

       category:
         $ref: '#/definitions/Category'
        description: "description testing"

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 with the YAML example where a schema has both $ref and description, then trace how the parser represents and processes that schema. Compare the current result with an earlier release if available, and verify that the description is preserved when parsing the example.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.