{"id":20839352,"url":"https://github.com/scalar/openapi-parser","last_synced_at":"2025-05-08T21:43:25.258Z","repository":{"id":221555294,"uuid":"750798430","full_name":"scalar/openapi-parser","owner":"scalar","description":"Modern OpenAPI parser written in TypeScript","archived":true,"fork":false,"pushed_at":"2024-08-28T11:38:13.000Z","size":38760,"stargazers_count":35,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-08T21:43:09.074Z","etag":null,"topics":["openapi","parser","scalar","swagger"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/scalar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-01-31T10:44:00.000Z","updated_at":"2024-11-15T14:48:22.000Z","dependencies_parsed_at":"2024-03-04T16:52:38.058Z","dependency_job_id":"a5d90e81-5e92-455b-9dc6-6c61ba47c4ce","html_url":"https://github.com/scalar/openapi-parser","commit_stats":null,"previous_names":["scalar/openapi-parser"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scalar%2Fopenapi-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scalar%2Fopenapi-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scalar%2Fopenapi-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scalar%2Fopenapi-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scalar","download_url":"https://codeload.github.com/scalar/openapi-parser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253153757,"owners_count":21862405,"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","parser","scalar","swagger"],"created_at":"2024-11-18T01:13:22.564Z","updated_at":"2025-05-08T21:43:25.238Z","avatar_url":"https://github.com/scalar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!WARNING]  \n\u003e We moved `@scalar/openapi-parser` to [https://github.com/scalar/scalar](https://github.com/scalar/scalar/tree/main/packages/openapi-parser)\n\n# Scalar OpenAPI Parser\n\n[![CI](https://github.com/scalar/openapi-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/scalar/openapi-parser/actions/workflows/ci.yml)\n[![Contributors](https://img.shields.io/github/contributors/scalar/openapi-parser)](https://github.com/scalar/openapi-parser/graphs/contributors)\n[![GitHub License](https://img.shields.io/github/license/scalar/openapi-parser)](https://github.com/scalar/openapi-parser/blob/main/LICENSE)\n[![Discord](https://img.shields.io/discord/1135330207960678410?style=flat\u0026color=5865F2)](https://discord.gg/scalar)\n\nModern OpenAPI parser written in TypeScript with support for OpenAPI 3.1, OpenAPI 3.0 and Swagger 2.0.\n\n## Goals\n\n- [x] Written in TypeScript\n- [x] Runs in Node.js and in the browser (without any polyfills or configuration)\n- [x] Tested with hundreds of real world examples\n- [ ] Amazing error output\n- [ ] Support for OpenAPI 4.0 👀\n\n## Installation\n\n```bash\nnpm add @scalar/openapi-parser\n```\n\n## Usage\n\n### Validate\n\n```ts\nimport { validate } from '@scalar/openapi-parser'\n\nconst file = `{\n  \"openapi\": \"3.1.0\",\n  \"info\": {\n    \"title\": \"Hello World\",\n    \"version\": \"1.0.0\"\n  },\n  \"paths\": {}\n}`\n\nconst { valid, errors } = await validate(file)\n\nconsole.log(valid)\n\nif (!valid) {\n  console.log(errors)\n}\n```\n\n### Resolve references\n\n```ts\nimport { dereference } from '@scalar/openapi-parser'\n\nconst specification = `{\n  \"openapi\": \"3.1.0\",\n  \"info\": {\n    \"title\": \"Hello World\",\n    \"version\": \"1.0.0\"\n  },\n  \"paths\": {}\n}`\n\nconst { schema, errors } = await dereference(specification)\n```\n\n### Modify an OpenAPI specification\n\n```ts\nimport { filter } from '@scalar/openapi-parser'\n\nconst specification = `{\n  \"openapi\": \"3.1.0\",\n  \"info\": {\n    \"title\": \"Hello World\",\n    \"version\": \"1.0.0\"\n  },\n  \"paths\": {}\n}`\n\nconst { specification } = filter(specification, (schema) =\u003e !schema?.['x-internal'])\n```\n\n### Upgrade your OpenAPI specification\n\nThere’s an `upgrade` command to upgrade all your OpenAPI specifications to the latest OpenAPI version.\n\n\u003e ⚠️ Currently, only an upgrade from OpenAPI 3.0 to OpenAPI 3.1 is supported. Swagger 2.0 is not supported (yet).\n\n```ts\nimport { upgrade } from '@scalar/openapi-parser'\n\nconst { specification } = upgrade({\n  openapi: '3.0.0',\n  info: {\n    title: 'Hello World',\n    version: '1.0.0',\n  },\n  paths: {},\n})\n\nconsole.log(specification.openapi)\n// Output: 3.1.0\n```\n\n### Pipeline syntax\n\n```ts\nimport { openapi } from '@scalar/openapi-parser'\n\nconst specification = …\n\n// New pipeline …\nconst result = openapi()\n  // loads the specification …\n  .load(specification)\n  // upgrades to OpenAPI 3.1 …\n  .upgrade()\n  // removes all internal operations …\n  .filter((schema) =\u003e !schema?.['x-internal'])\n  // done!\n  .get()\n```\n\n### Then/Catch syntax\n\nIf you’re more the then/catch type of guy, that’s fine:\n\n```ts\nimport { validate } from '@scalar/openapi-parser'\n\nconst specification = …\n\nvalidate(specification, {\n  throwOnError: true,\n})\n.then(result =\u003e {\n  // Success\n})\n.catch(error =\u003e {\n  // Failure\n})\n```\n\n### TypeScript\n\nIf you just look for our types, you can install the package separately:\n\n```bash\nnpm add @scalar/openapi-types\n```\n\nAnd use it like this:\n\n```ts\nimport type { OpenAPI } from '@scalar/openapi-types'\n\nconst file: OpenAPI.Document = {\n  openapi: '3.1.0',\n  info: {\n    title: 'Hello World',\n    version: '1.0.0',\n  },\n  paths: {},\n}\n```\n\n### Advanced: URL and file references\n\nYou can reference other files, too. To do that, the parser needs to know what files are available.\n\n```ts\nimport { dereference, load } from '@scalar/openapi-parser'\nimport { fetchUrls } from '@scalar/openapi-parser/plugins/fetch-urls'\nimport { readFiles } from '@scalar/openapi-parser/plugins/read-files'\n\n// Load a file and all referenced files\nconst { filesystem } = await load('./openapi.yaml', {\n  plugins: [\n    readFiles(),\n    fetchUrls({\n      limit: 5,\n    }),\n  ],\n})\n\n// Instead of just passing a single specification, pass the whole “filesystem”\nconst result = await dereference(filesystem)\n```\n\nAs you see, `load()` supports plugins. You can write your own plugin, if you’d like to fetch API defintions from another data source, for example your database. Look at the source code of the `readFiles` to learn how this could look like.\n\n#### Directly load URLs\n\nOnce the `fetchUrls` plugin is loaded, you can also just pass an URL:\n\n```ts\nimport { dereference, load } from '@scalar/openapi-parser'\nimport { fetchUrls } from '@scalar/openapi-parser/plugins/fetch-urls'\n\n// Load a file and all referenced files\nconst { filesystem } = await load(\n  'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',\n  {\n    plugins: [fetchUrls()],\n  },\n)\n```\n\n#### Intercept HTTP requests\n\nIf you’re using the package in a browser environment, you may run into CORS issues when fetching from URLs. You can intercept the requests, for example to use a proxy, though:\n\n```ts\nimport { dereference, load } from '@scalar/openapi-parser'\nimport { fetchUrls } from '@scalar/openapi-parser/plugins/fetch-urls'\n\n// Load a file and all referenced files\nconst { filesystem } = await load(\n  'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',\n  {\n    plugins: [\n      fetchUrls({\n        fetch: (url) =\u003e fetch(url.replace('BANANA.net', 'jsdelivr.net')),\n      }).get('https://cdn.BANANA.net/npm/@scalar/galaxy/dist/latest.yaml'),\n    ],\n  },\n)\n```\n\n## Community\n\nWe are API nerds. You too? Let’s chat on Discord: \u003chttps://discord.gg/scalar\u003e\n\n## Thank you!\n\nThanks a ton for all the help and inspiration:\n\n- [@philsturgeon](https://github.com/philsturgeon) to make sure we build something we won’t hate.\n- We took a lot of inspiration from [@seriousme](https://github.com/seriousme) and his package [openapi-schema-validator](https://github.com/seriousme/openapi-schema-validator) early-on.\n- You could consider this package the modern successor of [@apidevtools/swagger-parser](https://github.com/APIDevTools/swagger-parser), we even test against it to make sure we’re getting the same results (where intended).\n- We stole a lot of example specification from [@mermade](https://github.com/mermade) to test against.\n\n## Contributors\n\n\u003c!-- readme: collaborators,contributors -start --\u003e\n\u003ctable\u003e\n\t\u003ctbody\u003e\n\t\t\u003ctr\u003e\n            \u003ctd align=\"center\"\u003e\n                \u003ca href=\"https://github.com/hanspagel\"\u003e\n                    \u003cimg src=\"https://avatars.githubusercontent.com/u/1577992?v=4\" width=\"100;\" alt=\"hanspagel\"/\u003e\n                    \u003cbr /\u003e\n                    \u003csub\u003e\u003cb\u003ehanspagel\u003c/b\u003e\u003c/sub\u003e\n                \u003c/a\u003e\n            \u003c/td\u003e\n            \u003ctd align=\"center\"\u003e\n                \u003ca href=\"https://github.com/marclave\"\u003e\n                    \u003cimg src=\"https://avatars.githubusercontent.com/u/6176314?v=4\" width=\"100;\" alt=\"marclave\"/\u003e\n                    \u003cbr /\u003e\n                    \u003csub\u003e\u003cb\u003emarclave\u003c/b\u003e\u003c/sub\u003e\n                \u003c/a\u003e\n            \u003c/td\u003e\n            \u003ctd align=\"center\"\u003e\n                \u003ca href=\"https://github.com/amritk\"\u003e\n                    \u003cimg src=\"https://avatars.githubusercontent.com/u/2039539?v=4\" width=\"100;\" alt=\"amritk\"/\u003e\n                    \u003cbr /\u003e\n                    \u003csub\u003e\u003cb\u003eamritk\u003c/b\u003e\u003c/sub\u003e\n                \u003c/a\u003e\n            \u003c/td\u003e\n            \u003ctd align=\"center\"\u003e\n                \u003ca href=\"https://github.com/Drew-Kimberly\"\u003e\n                    \u003cimg src=\"https://avatars.githubusercontent.com/u/11247544?v=4\" width=\"100;\" alt=\"Drew-Kimberly\"/\u003e\n                    \u003cbr /\u003e\n                    \u003csub\u003e\u003cb\u003eDrew-Kimberly\u003c/b\u003e\u003c/sub\u003e\n                \u003c/a\u003e\n            \u003c/td\u003e\n            \u003ctd align=\"center\"\u003e\n                \u003ca href=\"https://github.com/tmcw\"\u003e\n                    \u003cimg src=\"https://avatars.githubusercontent.com/u/32314?v=4\" width=\"100;\" alt=\"tmcw\"/\u003e\n                    \u003cbr /\u003e\n                    \u003csub\u003e\u003cb\u003etmcw\u003c/b\u003e\u003c/sub\u003e\n                \u003c/a\u003e\n            \u003c/td\u003e\n            \u003ctd align=\"center\"\u003e\n                \u003ca href=\"https://github.com/x-delfino\"\u003e\n                    \u003cimg src=\"https://avatars.githubusercontent.com/u/67192579?v=4\" width=\"100;\" alt=\"x-delfino\"/\u003e\n                    \u003cbr /\u003e\n                    \u003csub\u003e\u003cb\u003ex-delfino\u003c/b\u003e\u003c/sub\u003e\n                \u003c/a\u003e\n            \u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\u003ctbody\u003e\n\u003c/table\u003e\n\u003c!-- readme: collaborators,contributors -end --\u003e\n\nContributions are welcome! Read [`CONTRIBUTING`](https://github.com/scalar/openapi-parser/blob/main/CONTRIBUTING).\n\n## License\n\nThe source code in this repository is licensed under [MIT](https://github.com/scalar/openapi-parser/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscalar%2Fopenapi-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscalar%2Fopenapi-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscalar%2Fopenapi-parser/lists"}