{"id":16596501,"url":"https://github.com/mikestead/yaml-fragment","last_synced_at":"2025-10-29T12:31:20.534Z","repository":{"id":57402970,"uuid":"47542936","full_name":"mikestead/yaml-fragment","owner":"mikestead","description":"Generate a yaml document from smaller yaml documents","archived":false,"fork":false,"pushed_at":"2020-09-09T10:14:21.000Z","size":49,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-02T01:24:57.518Z","etag":null,"topics":["openapi","swagger","yaml"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikestead.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-12-07T09:39:03.000Z","updated_at":"2021-01-15T04:58:09.000Z","dependencies_parsed_at":"2022-09-16T21:41:02.149Z","dependency_job_id":null,"html_url":"https://github.com/mikestead/yaml-fragment","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikestead%2Fyaml-fragment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikestead%2Fyaml-fragment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikestead%2Fyaml-fragment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikestead%2Fyaml-fragment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikestead","download_url":"https://codeload.github.com/mikestead/yaml-fragment/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238825629,"owners_count":19537100,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openapi","swagger","yaml"],"created_at":"2024-10-11T23:53:26.446Z","updated_at":"2025-10-29T12:31:15.229Z","avatar_url":"https://github.com/mikestead.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Yaml Fragment 🗂️\n\n[![Build Status](https://travis-ci.org/mikestead/yaml-fragment.svg?branch=master)](https://travis-ci.org/mikestead/yaml-fragment) [![npm version](https://img.shields.io/npm/v/yaml-fragment.svg?style=flat-square)](https://www.npmjs.com/package/yaml-fragment)\n\nA tool to construct a yaml document from smaller yaml documents.\n\nAims to generate a single yaml document formatted exactly as you wrote your referenced fragments,\nmaking it easy to share with humans or machine.\n\n\u003e Transforming to json and back to yaml can lose some original formatting, because of this no\n\u003e transformation is done, instead each fragment is inserted where it's referenced in a parent document.\n\n[OpenAPI](https://www.openapis.org) [spec](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)\ngeneration is a primary use case, but it can be used anywhere you have an unwieldy yaml document\nwhich would be easier to maintain in fragments.\n\n## Installation\n\nYou can install globally\n\n```\nnpm install yaml-fragment -g\n```\n\nOr locally\n\n```\nnpm install yaml-fragment --save-dev\n```\n\n## Usage\n\n### CLI\n\nHere's an example to generate `api.yml` from fragments found in a `spec` directory, with `index.yml` being the root fragment. Also enables openapi processing defaults.\n\n```bash\nyaml-fragment -d ./spec -o api.yml --openapi\n```\n\n#### Options\n\n```bash\n  Usage: cli [options]\n\n  Options:\n\n    -V, --version                  output the version number\n    -d, --rootDir \u003cdir\u003e            root directory of your fragments\n    -i, --indexFile [fragment]     index document which references fragments (default: ./index.yml)\n    -o, --outFile \u003cfile\u003e           output file of the grouped fragments\n    --openapi                      enable openapi fragment processing\n    -h, --help                     output usage information\n```\n\n### Code\n\nA similar example from the CLI one above.\n\n```javascript\nimport { genDocument } from 'yaml-fragment'\n\ngenDocument({\n  rootDir: './spec',  // base directory of fragments, with default of index.yml root document\n  outFile: 'api.yml', // the file to generate\n  openapi: true       // enable openapi processing defaults\n}}\n```\n\n#### Options\n\n- `rootDir: string` root directory of your fragments\n- `indexFile: string` index document which references fragments (default: ./index.yml)\n- `outFile: string` output file of the grouped fragments\n- `openapi: bool` enable openapi fragment processing. See OpenAPI section below.\n- `indent: string` indentation to use in yaml. Defaults to two spaces.\n- `formatMapKey` function which returns a function, given a directory path, to format a [parsed path object](https://nodejs.org/api/path.html#path_path_parse_pathstring) to a yaml map key. Defaults to return raw filename.\n- `sortCollection` function which returns a function, given a directory path, which sorts keys of a collection. Defaults to use [localeCompare](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare)\n- `quoteMapKeyRegex` regex to test map keys. If it fails the key will be wrapped in quotes. Defaults to wrap anything starting with a number.\n- `relativePaths` true if using relative paths in generated collection files. Defaults to true.\n\n### Fragments\n\nStart with a base document which includes `$ref`s to local fragments.\n\n_Important: To be replaced, $ref paths must begin with`./`or`../`._\n\n#### index.yml\n\n```yaml\nswagger: '2.0'\ninfo:\n  $ref: ./info.yml\nhost: petstore.swagger.io\nbasePath: /v1\nschemes:\n  - http\nconsumes:\n  - application/json\nproduces:\n  - application/json\npaths:\n  $ref: ./paths/.map.yml\ndefinitions:\n  $ref: ./definitions/.map.yml\n```\n\n#### Maps\n\nTo generate a yaml map based on each fragment file in a directory, simply target\nthat directory with a `.map.yml` file as seen above. _This file shouldn't exist on disk._\n\nDuring document generation any `.map.yml` will be populated in memory with references\nto each yaml fragment file in the same directory, e.g.\n\n```yaml\nError:\n  $ref: ./Error.yml\nPet:\n  $ref: ./Pet.yml\nPets:\n  $ref: ./Pets.yml\n```\n\nThe key for each defaults to the filename it references, however you can process these names\nvia the option `formatMapKey`. For example if the key is an OpenAPI path we can use underscores\nin the filename to represent forward slash and then replace these during generation.\n\n    options.formatMapKey = (dirPath) =\u003e file =\u003e file.name.split('_').join('/')\n\nThis would convert the filename `_pets_{petId}` to the key `/pets/{petId}` and is\none of the defaults applied when the `openapi` options is present.\n\n#### Lists\n\nTo generate a yaml list based on each fragment file in a directory, simply target\nthat directory with a `.list.yml` file (much the same a `.map.yml`). _This file shouldn't exist on disk._\n\nDuring document generation any `.list.yml` will be populated in memory with references\nto each yaml fragment file in the same directory, e.g.\n\n```yaml\n- $ref: ./Error.yml\n- $ref: ./Pet.yml\n- $ref: ./Pets.yml\n```\n\n#### OpenAPI\n\nBy enabling the `openapi` option you'll turn on some automatic defaults to process an OpenAPI document.\n\nFirst, the `formatMapKey` option is set with a function to format OpenAPI path fragments which sit under a `paths` directory. This will turn file names like\n\n    _pets_{petId}.yml\n\nto map keys like\n\n    /pets/{petId}\n\nSecond, `sortCollection` is applied to path keys to place paths with parameters below paths with none. For example\n\n    GET /pets/popular\n    GET /pets/{petId}\n\nAlthough it's not at all great design to collide paths like this (really try and avoid it), it can\nhelp on some platforms like V8 (Node) where object iteration is deterministic. For example when adding\nExpress routes which are priority ordered.\n\n## Examples\n\n[See here](https://github.com/mikestead/yaml-fragment/tree/master/test/_fixture) for a more complete\nexample of fragments.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikestead%2Fyaml-fragment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikestead%2Fyaml-fragment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikestead%2Fyaml-fragment/lists"}