Update split document in-place

[redwyre]

I have a large openapi doc that uses a lot of local $refs (it totals like 600 yaml files), and is updated by multiple people, I was hoping I would be able to use this tool to update the documents in place but either I'm not using the right settings or that's not currently possible.

[thim81]

Hi @redwyre

Based on the current use-cases, today openAPI-format supports:

• Format/sort/filter one input OpenAPI document and write one output file.
• By default, it bundles/dereferences local and remote $refs into a single self-contained output.
• --no-bundle preserves $refs in the output.
• --split can generate a new multi-file structure from a document.

In your cases, it sounds like --split would be closed to your desired workflow.

Example:

openapi-format root.yaml -o dist/openapi.yaml --split

Once you have the new file structure, you can commit it in git and just rerun the openAPI-format with --split before or each commit.

Let me try to explain the process:

openapi-format first resolves the entire OpenAPI document into a single in-memory model before it performs any sorting or formatting.

The process looks like this:

1. It follows every local $ref.
2. It builds one complete OpenAPI object graph in memory.
3. It applies sorting, filtering, and formatting to that unified model.

For example, if your project looks like this:

paths/
  users.yaml
components/
  schemas/
    User.yaml
    Address.yaml

Internally, openapi-format effectively sees:

OpenAPI
├── paths
│   └── /users
├── components
│   ├── User
│   └── Address

Once everything has been combined into a single object graph, the tool no longer operates on the original files individually. Objects may have been reordered or shifted relative to one another as part of the sorting process.

Because of this, openapi-format cannot reliably determine how to update each source file while preserving your project's custom file layout and organization.

Instead, when writing a multi-file output, it generates a logical split structure based on the sorted in-memory model.

Happy to discuss this further to fully understand your setup and use-case, to see if we can extend openAPI-format in logical way (if it is possible)