robertmassaioli / openapi-merge

Merge multiple OpenAPI 3.0 (Swagger) files together via a library or CLI tool.

The openapi-merge repository

Welcome to the openapi-merge repository. This library is intended to be used for merging multiple OpenAPI 3.0 files together. The most common reason that developers want to do this is because they have multiple services that they wish to expose underneath a single API Gateway. Therefore, even though this merging logic is sufficiently generic to be used for most use cases, some of the feature decisions are tailored for that specific use case.

Screenshots

(An example of creating an openapi-merge.json configuration file for the CLI tool)

About this repository

This is a multi-package repository that contains:

• The openapi-merge library:
• The openapi-merge CLI tool:

Depending on your use-case, you may wish to use the CLI tool or the library in your project. Please see the readme file of the specific package for more details.

Developing on openapi-merge

This project is a multi-package repository and uses the bolt tool to manage these packages in one development experience.

After checking out this repository, you can run the following command to install the required dependencies:

bolt install

You can then test running the CLI tool by running:

yarn cli

If you wish to ensure that you can develop on the openapi-merge library in parallel to the openapi-merge-cli tool then you must run the Typescript build for openapi-merge in watch mode. You can do this by:

bolt w openapi-merge build -w

This will ensure that the Typescript is compiled into JavaScript so that it can be used by the openapi-merge-cli tool.

For the other operations that you wish to perform, please see the package.json of the other packages in this repository.

openapi-merge's Issues

Support Swagger v2

Moved from: https://bitbucket.org/echo_rm/openapi-merge/issues/2/support-swagger-v2

The idea behind this issue is, if we happen to be given a Swagger V2 file, then we should automatically convert it into an OpenAPI file using swagger2openapi: https://github.com/Mermade/oas-kit/blob/master/packages/swagger2openapi/README.md

Then we just process it like normal.

This way, we have support for OpenAPI and Swagger V2 in the one tool.

Date example changed type after merging

Moved from: https://bitbucket.org/echo_rm/openapi-merge/issues/8/date-example-changed-type-after-merging

Hi, when I’m trying to merge 2 specs and one includes a schema with property of type string and format date and has an example specified e.g. 2017-07-21, after I run the openapi-merge-cli the example changes from date to date-time. E.g. 2017-07-21T00:00:00.000Z

I created a repository with an example: https://github.com/falnyr/openapi-merge-date-bug

x-tagGroups Only keeps first file's tags

Hi,

I'm using the cli to merge 2 openapi json files. The x-tagGroups in the result json only has the first file's x-tagGroups array.

Any ideas?

dispute.alwaysApply is not effective on `operationId`s

Hi and thanks for the great library / CLI!

I've just started using dispute with the alwaysApply option. While it works great for schema components, the dispute is only effective on operationId (in paths) when there is indeed a conflict (maybe because of this line?). I would have expected the alwaysApply option to also apply on all operationIds.

Could this please be fixed, or added as a separate option if this was intentional?

Cheers,

description.title in config file is not accepted as schema validation error

Using:

$ openapi-merge-cli --version
1.3.1

Given this config file openapi-merge.yaml :

inputs:
  - inputFile: a.yaml
    description:
      append: true
      title: Customer Accounts
  - inputFile: bi.yaml
    description:
      append: false
output: ../gen/openapi.yaml

when running

openapi-merge-cli --config openapi-merge.yaml

I get an error

data.inputs[0].description.title should be object, data.inputs[0] should NOT have additional properties, data.inputs[0].description.title should be object, data.inputs[0] should NOT have additional properties, data.inputs[0] should match some schema in anyOf

If I remove the title: line, there is no error

In the distribution, the configuration.schema.json has a DescriptionTitle schema with

            "title": "DescriptionTitle",
            "type": "object"

which I think should be "type": "string"

The documentation says:

description.title: An optional field, that lets you spefify a custom heading for this inputs description when it is merged together in the output OpenAPI file.

but does not describe this as an object.

After looking at the code I was able to get this to work by using description.title.value

inputs:
  - inputFile: a.yaml
    description:
      append: true
      title:
        value: Customer Accounts
  - inputFile: bi.yaml
    description:
      append: false
output: ../gen/openapi.yaml

See src/examples-for-schema.ts which has examples showing a title.headingLevel is also supported; headingLevel: 6

So it looks like the doc is incorrect. I can file a PR.

excludeTags working but not removing unwanted schemas

If I exclude some tags, I would expect the schemas attached to those tags to also be removed (unless it s also used by another endpoint

fixing openapi version

When merging multiple OpenAPI files that are version 3.0.0, the resulting file currently always has version 3.0.3. Is it possible to fix a particular version? In this case, the output OpenAPI version would be 3.0.0.

Sounds minor, but some tools like Postman are very strict on the API versions that are imported.

Leading '/' is stripped from output path

It seems like leading a / is stripped from the input and output files. I like to write my output to /tmp/ to do some additional processing outside of my repository, however openapi-merge-cli wants to write the file to a relative path.

The stripping also applies to ./ according to the logs, which however is not a problem, since it's already a relative path, but in my eyes the specified file paths shouldn't be modified in any way to allow both relative and absolute paths.

openapi-merge.json:

{
  "inputs": [
    {
      "inputFile": "./my-api/src/main/resources/api.yaml"
    }
  ],
  "output": "/tmp/merged-api-output.yaml"
}

Error:

## /usr/local/Cellar/node/19.4.0_1/bin/node: Running v1.3.1 (+1ms)
## Loaded the configuration: 1 inputs (+69ms)
## Loading input 0: my-api/src/main/resources/api.yaml (+1ms)
## Loaded the inputs into memory, merging the results. (+7ms)
## Inputs merged, writing the results out to 'tmp/merged-api-output.yaml' (+4ms)
An uncaught exception was thrown Error: ENOENT: no such file or directory, open 'tmp/merged-api-output.yaml'

_{(on a side note: Thx for the great tool ❤️)}

Resolve and/or bundle external references

Many people define references in OpenAPI files such that those references are not internal to the OpenAPI file. As a result, they expect that when they use the openapi-merge library or CLI tool, that it will merge everything together for them.

We could solve this problem in one of two ways:

1. Pre-bundle all of the references into each individual OpenAPI file and then rely upon de-duplication to end up with a minimal OpenAPI file.
2. Support external references such that the merging algorithm can load them all itself and then bundle only the components that are required.

At this point in time. I think that I have a preference for Option 1 because it means that we can offload this problem to another tool and then just ask people to integrate that together instead to form a cohesive whole. It is a nice way to introduce composition into the flow with a bunch of specific tools that compose together nicely. We can also then just make the CLI tool integrate that by default so that the CLI tool works like people expect.

It is also worth noting that the merge function currently expects all of the OpenAPI files to be pre-downloaded, that allows that function to be synchronous (which is good and reduces complexity). Attempting to load the schemas while we loaded external schemas would be an architectural mistake, because it would be a poor separation of concerns. Instead the merge function could be modified to have a pre-downloaded mapping of Reference => Schema that it can use in a synchronous manner.

merging does not resolve $ref

Perhaps this is beyond the scope of this tool, but I'd like it to resolve $ref correctly when merging.

When merging two openapi files where a.yaml references resources in b.yaml, for example:

a.yaml contains

components:
  responses:
    '304':
      $ref: "b.yaml#/components/responses/304"
    '400':
      $ref: "b.yaml#/components/responses/400"

and b.yaml defines those responses:

components:
  responses:
    '304':
      description: >-
        Not Modified. The resource has not been modified since it was last fetched.
    '400':
      description: >-
        Bad Request.
        The request body or one or more of the query parameters was not well formed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problemResponse'
    ...

when merging, the output file does not resolve and merge the references. The output file repeats the references
and then adds a suffix where there is duplication:

components:
  responses:
    '304':
      $ref: b.yaml#/components/responses/304
    '400':
      $ref: b.yaml#/components/responses/400
    '3041':
      description: >-
        Not Modified. The resource has not been modified since it was last fetched.
    '4001':
      description: >-
        Bad Request. The request body or one or more of the query parameters was not well formed. 
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problemResponse'

and the resulting file does not standalone -- it still requires b.yaml

To properly resolve the $ref this should be

components:
  responses:
    '304':
      $ref: #/components/responses/304`
    '400':
      $ref: #/components/responses/4001

This should work for all $ref in the OpenAPI files (in schemas, etc.).

Exception when merging files with nullable enums

Command I'm running:

% npx openapi-merge-cli --config openapi-merge.yaml

Files i'm using:

File 1:

openapi: 3.0.3
info:
  title: Test
  version: 0.0.1
paths:
  /some/endpoint1:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/someSchema'
      responses:
        '200':
          description: successful operation
components:
  schemas:
    someSchema:
      type: object
      properties:
        someField:
          type: string
          nullable: true
          enum:
            - "A"
            - "B"
            - "C"
            - null

File 2 (identical to File 1, except for endpoint):

openapi: 3.0.3
info:
  title: Test
  version: 0.0.1
paths:
  /some/endpoint2:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/someSchema'
      responses:
        '200':
          description: successful operation
components:
  schemas:
    someSchema:
      type: object
      properties:
        someField:
          type: string
          nullable: true
          enum:
            - "A"
            - "B"
            - "C"
            - null

Output:

## /opt/homebrew/Cellar/node/20.8.0/bin/node: Running v1.3.1 (+1ms)
## Loaded the configuration: 2 inputs (+36ms)
## Loading input 0: specs/test1.yaml (+0ms)
## Loading input 1: specs/test2.yaml (+0ms)
## Loaded the inputs into memory, merging the results. (+1ms)
An uncaught exception was thrown TypeError: Cannot use 'in' operator to search for '$ref' in null
    at Object.isReference (/Users/.../node_modules/atlassian-openapi/lib/type-checks.js:85:48)
    at compare (/Users/.../node_modules/openapi-merge/dist/component-equivalence.js:63:51)
    at /Users/.../node_modules/openapi-merge/dist/component-equivalence.js:80:39
    at Array.every (<anonymous>)
    at compare (/Users/.../node_modules/openapi-merge/dist/component-equivalence.js:80:26)
    at /Users/.../node_modules/openapi-merge/dist/component-equivalence.js:80:39
    at Array.every (<anonymous>)
    at compare (/Users/.../node_modules/openapi-merge/dist/component-equivalence.js:80:26)
    at /Users/.../node_modules/openapi-merge/dist/component-equivalence.js:80:39
    at Array.every (<anonymous>)

Platform: macOS Ventura (22D49)
Node version:

% /opt/homebrew/Cellar/node/20.8.0/bin/node -v
v20.8.0

Merge of reference files

Moved from: https://bitbucket.org/echo_rm/openapi-merge-cli/issues/5/merge-of-reference-files

Some of my specs that I am hoping to merge have common reference files. They use something like this:

      parameters: {
        "$ref": "parameters.json#/appKey"
      }

Since several services access the same parameters.json file, I don’t want to need to move those definitions into the specs. I could change the ref to a full URL, but then I run into issues with a stage and prod set of docs.

I am not certain the best solution. I am fine with adding the reference files to the merge, but they need some hacking right now to merge cleanly AND I still need to go in and replace the paramters.json with an in file reference '#/components/parameters/appKey`.

‌

One thought was to have a different input for reference files that would merge json into the structure with a specified prefix (components/parameters). It could merge at that level (skipping currently required higher level merge items). Then replace any $ref: {originalPrefix}# with $ref: #{mergePrefix}

{
  "inputs": [
    {
      "inputURL": "https://example.com/apidocs/a.json",
    },
    {
      "inputURL": "https://example.com/apidocs/b.json",
    },
    {
      "inputReferenceURL": "https://example.com/apidocs/parameters.json",
      "mergePrefix": "components/parameters",
      "originalReferencePrefix": "parameters.json"
    }
  ],
}

Issue on discriminator mapping

References in the mapping key of discriminator schema component is not resolved during the openapi-merge with dispute prefix.

References are not renamed properly and the final openapi file is invalid.

For example

The first openapi file openapi1.yml

openapi: 3.0.3
info:
  title: Swagger
  description: description
  version: 1.0.0
servers:
  - url: http://example.com
tags:
  - name: pet
    description: Everything about your Pets
    externalDocs:
      description: Find out more
      url: http://swagger.io
paths:
  /pet:
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: Add a new pet to the store
      operationId: addPet
      requestBody:
        description: Create a new pet in the store
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Pet'
                - $ref: '#/components/schemas/Pet2'
              discriminator:
                propertyName: name
                mapping:
                  pet: '#/components/schemas/Pet'
                  pet2: '#/components/schemas/Pet2'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      required:
        - id
        - name
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: doggie
    Pet2:
      required:
        - id
        - name
        - lastName
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: doggie
        lastName:
          type: string
          example: doogle
  requestBodies:
    Pet:
      description: Pet object that needs to be added to the store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Pet'

The second openapifile : openapi2.yml

openapi: 3.0.3
info:
  title: Swagger
  description: description
  version: 1.0.0
servers:
  - url: http://example.com
tags:
  - name: pet
    description: Everything about your Pets
    externalDocs:
      description: Find out more
      url: http://swagger.io
paths:
  /pet2:
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: Add a new pet to the store
      operationId: addPet
      requestBody:
        description: Create a new pet in the store
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Pet'
                - $ref: '#/components/schemas/Pet2'
              discriminator:
                propertyName: name
                mapping:
                  pet: '#/components/schemas/Pet'
                  pet2: '#/components/schemas/Pet2'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      required:
        - id
        - name
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: doggie
    Pet2:
      required:
        - id
        - name
        - lastName
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: doggie
        lastName:
          type: string
          example: doogle
  requestBodies:
    Pet:
      description: Pet object that needs to be added to the store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Pet'

And the merge configuration : (according to the openapi-merge-cli package)

{
    "inputs": [
      {
        "inputFile": "./openapi1.yml",
        "dispute": {
            "prefix": "openapi1",
            "alwaysApply": true
        }
      },
      {
        "inputFile": "./openapi2.yml",
        "dispute": {
            "prefix": "openapi2",
            "alwaysApply": true
        }
      }
    ], 
    "output": "./openap3.yml"
  }

The result is :

openapi: 3.0.3
info:
  title: Swagger
  description: description
  version: 1.0.0
servers:
  - url: 'http://example.com'
tags:
  - name: pet
    description: Everything about your Pets
    externalDocs:
      description: Find out more
      url: 'http://swagger.io'
paths:
  /pet:
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: Add a new pet to the store
      operationId: addPet
      requestBody:
        description: Create a new pet in the store
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/openapi1Pet'
                - $ref: '#/components/schemas/openapi1Pet2'
              discriminator:
                propertyName: name
                mapping:
                  pet: '#/components/schemas/Pet'
                  pet2: '#/components/schemas/Pet2'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/openapi1Pet'
  /pet2:
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: Add a new pet to the store
      operationId: openapi2addPet
      requestBody:
        description: Create a new pet in the store
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/openapi2Pet'
                - $ref: '#/components/schemas/openapi2Pet2'
              discriminator:
                propertyName: name
                mapping:
                  pet: '#/components/schemas/Pet'
                  pet2: '#/components/schemas/Pet2'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/openapi2Pet'
components:
  schemas:
    openapi1Pet:
      required:
        - id
        - name
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: doggie
    openapi1Pet2:
      required:
        - id
        - name
        - lastName
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: doggie
        lastName:
          type: string
          example: doogle
    openapi2Pet:
      required:
        - id
        - name
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: doggie
    openapi2Pet2:
      required:
        - id
        - name
        - lastName
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: doggie
        lastName:
          type: string
          example: doogle
  requestBodies:
    openapi1Pet:
      description: Pet object that needs to be added to the store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/openapi1Pet'
    openapi2Pet:
      description: Pet object that needs to be added to the store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/openapi2Pet'

Where the following content is invalid :

          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/openapi1Pet'
                - $ref: '#/components/schemas/openapi1Pet2'
              discriminator:
                propertyName: name
                mapping:
                  pet: '#/components/schemas/Pet'
                  pet2: '#/components/schemas/Pet2'

Reference of components are well renamed in the oneOf property but not in the mapping discriminator.

Uncaught exception with common model

Moved from: https://bitbucket.org/echo_rm/openapi-merge-cli/issues/16

I’m working with an API in which every object is defined in its own OAS definition file. The majority of them have this in the components section:

  responses:
    400error:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: ../../common/models/errorresponse.schema.yaml

If I set my openapi-merge.json file to only a single input file, it works fine. If I set it to two input files in which only one of them has the 400error defined, it works fine. However, if more than one input file as the 400error defined I get this error:

An uncaught exception was thrown Error: Could not resolve reference: ../../common/models/errorresponse.schema.yamlat isSchemaOrThrowError (C:\Users\steve.nay\node_modules\openapi-merge\dist\component-equivalence.js:27:15)at compare (C:\Users\steve.nay\node_modules\openapi-merge\dist\component-equivalence.js:66:29)at C:\Users\steve.nay\node_modules\openapi-merge\dist\component-equivalence.js:79:39at Array.every (<anonymous>)at compare (C:\Users\steve.nay\node_modules\openapi-merge\dist\component-equivalence.js:79:26)at C:\Users\steve.nay\node_modules\openapi-merge\dist\component-equivalence.js:79:39at Array.every (<anonymous>)at compare (C:\Users\steve.nay\node_modules\openapi-merge\dist\component-equivalence.js:79:26)at C:\Users\steve.nay\node_modules\openapi-merge\dist\component-equivalence.js:79:39at Array.every (<anonymous>)

So something about that 400error being defined in multiple files is throwing this error. I tried setting a different disputePrefix for each input file, but that didn’t make any difference.

Ref Paths don't get adjusted to account for different directories

Reference paths do not get updated when merging. Imagine that Proj2/OpenAPI.json references a component from SomeRef.json. When this file gets merged into OpenAPIOut.json, the $ref path still relative to Proj2 dir, rather than Proj1 (output dir).

Folder structure:
Root

• Proj1
  • OpenAPI.json
  • openapi-merge.json
• Proj2
  • OpenAPI.json
  • SomeRef.json

Proj2/OpenAPI.json

"parameters": [
  {
    "$ref": "SomeRef.json#/components/parameters/myParam"
  }
]

In OpenAPIOut.json should be, but is same as above:

"parameters": [
  {
    "$ref": "../Proj2/SomeRef.json#/components/parameters/myParam"
  }
]

Input:
openapi-merge.json

{
  "inputs": [
    {
      "inputFile": "OpenAPI.json"
    },
    {
      "inputFile": "../Proj2/OpenAPI.json"
    }
  ],
  "output": "OpenAPIOut.json"
}

Always add model disputePrefix

Moved from: https://bitbucket.org/echo_rm/openapi-merge-cli/issues/15/add-model-prefix-always

Initial Post

Hey mate

Would it be possible to use the disputePrefix ALWAYS for the Models and Components?

Maybe by adding a further configOption: alwaysUseDisputePrefix

That would really fit my need.

Thanks

Robert Response

Everything is possible but can you expand a bit more on why you want this feature? 🙂

For example, why not just put in the prefixes in the original schema file? Also, do you still expect deduplication to occur if you use a fixed prefix?

Daniel Response

Thanks for your Answer!

I am mergin a couple of API-Specs together and serving it in one place, at my gateway api.
So i have api-doc A which has Models like (Device, Measurement, Customer, Contact), with disputePrefix A
And i have api-doc B which has Modles like (Weather, Measurement, Customer, Location) with disputePrefix B

Obviously Measurement and Customer will conflict.
Device, Weather and Location will not conflict.

Having that i merge my Api-doc and create via codegen ONE client. There now i Have These Models:

Device, AMeasurement, BMeasurement, ACustomer, BCustomer, Weather, Contact, Location

So far so good. i implement and work with the models on my client.

BUT now i add a third api-doc to my Gateway-api-doc:
api-doc C which has Models like (Contact) with disputePrefix C

After the merge i end UP with my former Contact Model from Api-Doc A is renamed to AContact and is breaking my code in the client. (Because the ModelName changed, because API-doc C has also a Model called Contact → resolving into CContact).

In order to prevent those changes i would like to Prefix each Model from the very beginning, not only in conflict. This will prevent a rename of the model in the future in case of conflict.

So my answer to Question 1)
Because i do not have the power to change the Schema-Files in the server, nor do i want to “parse” and “prefix” models myself in the json-api-doc
To Question 2)
If i use a fixed prefix i would suppose no deduplication is necessary anymore, except the case i would give two input-sources the same prefix, but then… well. then it’s my fault 😉

Could I clarify?

Daniel follow up

hello Robert

Any news on this?

Kind regards

Daniel

Need code examples

I am sorry for asking, if I want generate 2 swagger specs that are a bit differ from each other in some routes, does openapi-merge will help me?

Is there any minimal exapmle code how to run merging like "hello world" + "hello world 2" to clone from git and run?

Possible to skip duplicate paths?

Is it possible to add some flag in the config file openapi-merge.json which would skip duplicate paths instead of throwing this error?

Error merging files: Input 2: The path '/api/associations' maps to '/api/associations' and this has already been added by another input file (duplicate-paths)

I have a use case where multiple Swagger specification files could have the same path and i am unifying them into a single file.
Thanks!

Merge OpenAPI paths based on specific tags

Hello,

I'm currently exploring the capabilities of OpenAPI and I'm curious if there's a way to merge multiple service Swagger files while selecting only the paths that have a specific tag. I've reviewed the documentation but couldn't find any details on this particular functionality.

For instance, let's consider the following scenario:
I have a merge.json file with inputs from multiple services:
{
"inputs": [
{
"inputFile": "service1/dist/functions/api/swagger.json"
},
{
"inputFile": "service2/dist/functions/api/swagger.json"
},
{
"inputFile": "service3/dist/functions/api/swagger.json"
}
],
"output": "./dist/service.output.swagger.json"
}

In this scenario, I'd like to include only the paths from service1 Swagger that comply with the "Service1" tag. Paths from service1 that don't comply with this tag should be excluded from this merged Swagger. Using the Hidden() decorator isn't suitable for my needs, as I would like to include the other tags in different merged swaggers.

Thanks in advance!

Merge info.description

Moved from: https://bitbucket.org/echo_rm/openapi-merge/issues/1/merge-infodescription

For our use case it would be nice if the info.descriptions could also be merged. Currently, it only takes the info block from the root input file.

We are creating several output files by combining a template file containing some basic information in the info.description which is the same for all our API specifications. Futhermore, each API spec also has it’s own description.

Add a section to define the global title and description

Add a section in configuration file to define the global title and description of the merge schema

Authorization config for InputUrl

I have several input sources that are protected. Would be nice if user/password or api key could be define in the config file for an inputUrl.

Typescript `atlassian-openapi` is not compatible with `openapi-types` OpenAPI3 type

I am using @apidevtools/swagger-parser to parse URLS to Javascript objects, after which I want to merge them using this library, sadly I am getting the following error in Typescript due an incompatibility:

I've got two questions:

1. How does one solve this?
2. Why is Atlassian's specific OpenAPI used here and not the global (as far as I could find, official) one?

Merge securitySchemes of input files

At the moment only the securitySchemes item from the first file parsed is taken.

This behavior is not documented and also not expected. And leads to validation errors on the final schema, in case the security key in one of the files references a schema that was not merged.

The logical implementation would be to perform a merge of all securitySchemes found across all the input files. At least a warning should be raised to inform the user and prevent blind attempts.

Thanks.

Uncaught exception does not set failure status code

If openapi-merge-cli encounters an exception, I expect the command to exit with a non-zero status code to indicate that the command failed.

╭ ~/w/d (master =)
╰ → npx openapi-merge-cli
## /opt/homebrew/Cellar/node/19.4.0/bin/node: Running v1.3.1 (+0ms)
## Loaded the configuration: 11 inputs (+30ms)
An uncaught exception was thrown TypeError: Cannot use 'in' operator to search for '$ref' in null
    at Object.isReference (/Users/zacharyw/work/docs-network/node_modules/atlassian-openapi/lib/type-checks.js:85:48)
    at compare (/Users/zacharyw/work/docs-network/node_modules/openapi-merge/dist/component-equivalence.js:63:51)
    at /Users/zacharyw/work/docs-network/node_modules/openapi-merge/dist/component-equivalence.js:80:39
    at Array.every (<anonymous>)
    at compare (/Users/zacharyw/work/docs-network/node_modules/openapi-merge/dist/component-equivalence.js:80:26)
    at /Users/zacharyw/work/docs-network/node_modules/openapi-merge/dist/component-equivalence.js:80:39
    at Array.every (<anonymous>)
    at compare (/Users/zacharyw/work/docs-network/node_modules/openapi-merge/dist/component-equivalence.js:80:26)
    at /Users/zacharyw/work/docs-network/node_modules/openapi-merge/dist/component-equivalence.js:80:39
    at Array.every (<anonymous>)
╭ ~/w/d (master =)
╰ → echo $?
0

Using without config files

I think it can be nice to use without config files and relying on default sensible parameters.

npx openapi-merge-cli oas/my-app/file.yml

This is now working but requiring a config file. The output file can be defaulted into same directory of source file as file-merged.yml

Add support to merge duplicate oas paths using disputePrefix

Moved from: https://bitbucket.org/echo_rm/openapi-merge/issues/4/add-support-to-merge-duplicate-oas-paths

While trying to use your library we ran into an issue where our library has a preset amount of paths and a client application that can override them. Because we also use express-openapi-validator we need a cleanly merged OAS file between the two. I’ve created a fix and associated tests but am unable to open a pull request. You can find my proposed solution here: https://bitbucket.org/drethic/openapi-merge/src/oas-path-dispute-prefix/.

Thank you for your consideration in fixing this issue.

[edit-1]

Note: If the newer path only adds/overrides an operation it will replace the whole path. I’ll think on a cleaner solution but in the short term this should get one step closer to seamless merging of two files with identical paths.

Add license files to the sub-packages

What the title says.

When I run openapi-merge 1.3.2 on 3.0.1 yaml files, the Tag sections end up all grouped at the top

When I run openapi-merge 1.3.2 on 3.0.1 yaml files, the Tag sections end up all grouped at the top

Do you have a setting that would allow the tags to display , instead, above the paths section that the tag is related to?

Were you aware of this issue?

It just makes the aggregated Swagger report harder to navigate when there is a lot of endpoints.

Merging Swagger and resolve identical components

Hello togehter,
I'm merging a Swagger and my Swagger contains two objects (in components) that are complete the same.
I think the merger wont resolve those objects. Instead it adds those objects with "Name1" additionally.
Is it possible to set a flag that will result in a Swagger that doesn't create objects that already there?
Is there a way to do this with the current openapi-merge?

This would help me a lot!

Thanks for your answer in advance.

Best regards Paul

feature request: oas 3.1 webhook

add webhooks merge, which is dropped now

Servers array is not concatenated/merged

Moved from: https://bitbucket.org/echo_rm/openapi-merge-cli/issues/8/servers-array-is-not-concatenated-merged

It looks like when merging it takes the 1st server array and doesn’t merge the remaining. When running locally with the merged json different paths or ports will not work correctly.

Add disputeSuffix support

Moved from: https://bitbucket.org/echo_rm/openapi-merge/issues/6/add-support-to-merge-with-disputesuffix

Hey

We would love to have ability to decide in case of merge conflict to either add prefix or suffix. If this is a valid feature, happy to issue PR and help with implementation.

Thanks,
Jacek

How can I merge to OpenAPI strings/objects instead of files?

First of all, thanks for this project, is what I need for my current gateway.

I'd like to use this library, but instead of giving a filepath or url I'd like to directly pass the string (or object) representing the OpenAPI definition. Is there a workaround to do that?

Thanks!