APIDevTools/swagger-cli

Feature Request: do not resolve references completely (cli param)

tricoos opened this issue · 1 comments

I created a large and structured definition with separate files for different components.
When executing swagger-cli all of the references are somewhat flattened so that they are not available as single reused components anymore but just plain copies of the definition.

This means that if I have a component like this and reuse it several times inside my definition the API user can by reading the definition see immediately that it is actually the same object. However, when I use swagger-cli that information is lost completely and the user might find out "accidentally" that I am returning the same structure with different API calls.

OrderPosition:
  type: object
  description: The order position object as returned from the API
  properties:
    id:
      type: integer
      readOnly: true
      example: 23454
    quantity:
      type: integer
      example: 10
    productId:
      type: integer
      example: 3847
    tsCreated:
      type: string
      readOnly: true
      description: Create timestamp in ISO8601 format
      example: "2021-09-10T12:19:53+00:00"
    tsUpdated:
      type: string
      readOnly: true
      description: Update timestamp in ISO8601 format
      example: "2021-09-10T12:19:53+00:00"

My expectation would be that such definitions are simply copied to the components object and referenced instead of copying the contents and losing the big picture.

Update: the same issue occurs with speccy (wework/speccy#315) and openapi-merge (robertmassaioli/openapi-merge#10)