search

thim81 / openapi-format

Format an OpenAPI document by ordering, formatting and filtering fields.
MIT License
77 stars 14 forks source link

Quotes around references to other files are incorrectly handled #98

Closed florentausha closed 4 months ago

florentausha commented 5 months ago

Hi,

When formatting this file, that has references to schemas defined in other files: 

openapi: 3.1.0
info:
  title: Example
  version: 1.0.0
paths:
  /v1/examples:
    get:
      summary: Get
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Example'
components:
  schemas:
    Example:
      type: object
      properties:
        id:
          $ref: './otherfile.yaml#/components/schemas/Id'

The following command npx openapi-format ./public/docs/example.yaml -o ./public/docs/example.yaml

Returns the following file:

openapi: 3.1.0
info:
  title: Example
  version: 1.0.0
paths:
  /v1/examples:
    get:
      summary: Get
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Example'
components:
  schemas:
    Example:
      type: object
      properties:
        id:
          $ref: ./otherfile.yaml#/components/schemas/Id

As you can see, quotes around $ref: './otherfile.yaml#/components/schemas/Id' get removed. Can I fix this by modifying my file?

florentausha commented 5 months ago

Temporarily fixed my issue by appending sed -i '' "s/^\( *\$ref: \)\(.*\.yaml#\/.*\)$/\1'\2'/g" $filepath To every OpenAPI format command (MacOS)

thim81 commented 4 months ago

hi @florentausha

We use @stoplight/yaml for handling the YAML files, which manipulates the "". https://github.com/thim81/openapi-format?tab=readme-ov-file#stoplight-studio

We have adopted the YAML parsing style from Stoplight Studio, by leveraging the @stoplight/yaml package for handling the parsing of OpenAPI YAML files.

By using the Stoplight YAML parsing, the results will be slightly different from when using a normal YAML parsing library, like js-to-yaml. We appreciate the Stoplight Studio tool, since it is an excellent GUI for working with OpenAPI documents for non-OpenAPI experts who will be contributing changes. By adopting the Stoplight Studio YAML parsing, the potential risk of merge conflicts will be lowered, which is the main reason why we opted for using the @stoplight/yaml package.

florentausha commented 4 months ago

@thim81 Thanks for your detailed answer, I'll close this issue then 👍