swagger-api / swagger-api/swagger-parser

Inline schemas get empty model name when title is empty

Open
#2,118 3 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

Description

When an inline schema has empty title, the resulted model has an empty name causing schema to not properly be resolved.

swagger-parser version

Version 2.1.22

OpenAPI declaration file content or url
openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  description: A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification
  termsOfService: http://swagger.io/terms/
  contact:
    name: Swagger API Team
    email: apiteam@swagger.io
    url: http://swagger.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: http://petstore.swagger.io/api
paths:
  /pet-types:
    post:
      description: Creates a new pet in the store.  Duplicates are allowed
      operationId: addPet
      requestBody:
        description: Pet to add to the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MegaPet'
      responses:
        '200':
          description: pet response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MegaPet'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  responses:
    BadRequest:
      description: Request rejected due to a structural or business validation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    MegaPet:
      properties:
        id:
          type: integer
          format: int64
        code:
          type: string
          format: byte
          example: MjIyMjIyMg==
        additionalCode:
          type: string
          format: binary
          example: MjIyMjIyMg==
        dateOfBirth:
          type: string
          format: date
          example: "2000-12-12"
        timeOfVaccination:
          type: string
          format: date-time
          example: 2012-01-24T15:54:14.876Z
        age:
          type: string
          pattern: "[0-9]+"
        owner:
          type: object
        previousOwner:
          type: object
          example: "prev owner"
        metadata:
          type: object
          maxProperties: 10
          additionalProperties:
            type: string
            maxLength: 256
        creator:
          title: ''
          description: ''
          type: object
          properties:
            id:
              description: ''
              type: string
              example: 63d415e0dd0d828c3a878548
              readOnly: true
            email:
              description: ''
              type: string
              example: fett@intergalactic.com
              readOnly: true
            displayName:
              description: ''
              type: string
              example: Boba Fett
              readOnly: true

Generation Details

Use the following code:

        OpenAPIParser openAPIV3Parser = new OpenAPIParser();
        ParseOptions options = new ParseOptions();
        options.setResolve(true);
        options.setFlatten(true);

        OpenAPI openAPI = openAPIV3Parser.readContents(Files.readString(Paths.get("openapi.yaml")), null, options).getOpenAPI();
        PathItem pathItem = openAPI.getPaths().get("/pet-types");

You can check the openAPI.getComponents.getSchemas() that it contains an empty model with an empty title and those 3 properties.

Screenshot 2024-08-12 at 22 12 02 Screenshot 2024-08-12 at 22 12 18
Steps to reproduce

See above

Suggest a fix

The issue seems to be this code from the io.swagger.v3.parser.util.InlineModelResolver class:

 private String resolveModelName(String title, String key) {
        if (title == null) {
            return uniqueName(key);
        } else {
            return uniqueName(title);
        }
    }

The fix is to test for empty strings also:

 private String resolveModelName(String title, String key) {
        if (StringUtils.isBlank(title)) {
            return uniqueName(key);
        } else {
            return uniqueName(title);
        }
    }

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 resolveModelName method in io.swagger.v3.parser.util.InlineModelResolver and reproduce the empty-title case using the OpenAPI declaration and parser options shown in the issue. Verify that an inline schema with a blank title receives a non-empty unique model name and that the resulting components schemas no longer contain an empty model.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi
Domain
api
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.