Suggestion: Merge configuration files into one

[wedi]

It would be nice to have just one configuration file as seen in most tools.

It looks like openapiformatrc[.(yaml|json)] would follow a common pattern.

[thim81]

@wedi Thanks (again) for the valuable feedback.

Which configurations would you like to see merged?

In the CI flow, that we are using, we use it to format and filter 1 OpenAPI and store multiple results in seperate OpenAPI files.

Example:

• public documentation for production
• internal preview documentation (which contains upcoming endpoints)
• an OpenAPI for Newman with a subset for tests.

[wedi]

That's a pretty neat workflow and I believe my suggestion wouldn't break it. You could keep the existing parameters and document that they overwrite the combined config file. (Although that might make it more complicated than it needs to be.)

Which configurations would you like to see merged?

All of them. 🤓 Similar to this:

{
  "file": "src/openapi.yaml",   // file and string or files and [] if you decide to allow multiple (globs)
  "filter": {
    "methods": [],
    "tags": [],
    "operationIds": [],
    "operations": [],
    "flags": [],
    "flagValues": [],
    "unusedComponents": [],
    "stripFlags": []
  },
  "lineWidth": -1,    // maybe 0 should do the same?
  "sort": {   // set to false for `no-sort`
    "root": ["openapi", "info", "servers", "paths", "components", "tags", "x-tagGroups", "externalDocs"],
    "get": ["operationId", "summary", "description", "parameters", "requestBody", "responses"],
    "post": ["operationId", "summary", "description", "parameters", "requestBody", "responses"],
    "put": ["operationId", "summary", "description", "parameters", "requestBody", "responses"],
    "patch": ["operationId", "summary", "description", "parameters", "requestBody", "responses"],
    "delete": ["operationId", "summary", "description", "parameters", "requestBody", "responses"],
    "parameters": ["name", "in", "description", "required", "schema"],
    "requestBody": ["description", "headers", "content", "links"],
    "responses": ["description", "headers", "content", "links"],
    "content": [],
    "components": ["parameters", "schemas"],
    "schema": ["description", "type", "items", "properties", "format", "example", "default"],
    "schemas": ["description", "type", "items", "properties", "format", "example", "default"],
    "properties": ["description", "type", "items", "format", "example", "default", "enum"]
  },
  "sort-components": [],
  "verbose": false,
}

I have two reasons for this suggestion.

1. Less clutter in already cluttered root directories
2. It would allow to replace
   openapi-format --sortFile .openapi-format-sort.json --sortComponentsFile .openapi-format-sort-components.json --filterFile .openapi-format-filter.json src/openapi.yaml -o src/openapi.yaml
   with
   openapi-format src/openapi.yaml -o src/openapi.yaml
   or even openapi-format . per my other suggestion.

Looking at eslint and prettier it seems -c|--config would be a sensible choice for a parameter to use a config file for a certain job and it would allow you to keep --configFile for backwards compatibility if desired (but it would break -c).

I digged into eslint and they use a highly customized config loader whereas prettier uses a library called cosmicconfig. They have lodash in their dependency list, too, so they might use that to merge with default settings.

[thim81]

@wedi I ll make a PR as soon as I have some time.

I ll make it a separate cli option, so that you can have the choice if you want to split the config or have 1 central file.