Gathering detailed insights and metrics for @readme/openapi-parser
Gathering detailed insights and metrics for @readme/openapi-parser
Comprehensive tooling for working with OpenAPI definitions.
Installations
npm install @readme/openapi-parserDeveloper Guide
BETA
Typescript
Yes
Module System
ESM
Min. Node Version
>=20
Node Version
20.19.0
NPM Version
lerna/8.2.1/node@v20.19.0+arm64 (darwin)
Score
97.7
Supply Chain
99.6
Quality
92.4
Maintenance
100
Vulnerability
99.6
License
Releases
110
Languages
3
TypeScript
JavaScript
HTML
TypeScript (99.55%)
JavaScript (0.43%)
HTML (0.02%)
Developer
readmeio
Download Statistics
Total Downloads
23,854,566
Last Day
17,998
Last Week
322,508
Last Month
1,386,218
Last Year
13,002,332
GitHub Statistics
MIT License
341 Stars
2,952 Commits
33 Forks
20 Watchers
6 Branches
53 Contributors
Updated on Jul 01, 2025
Bundle Size
336.32 kB
Minified
84.57 kB
Minified + Gzipped
Maintainers
12
Package Meta Information
Latest Version
4.1.0
Package Id
@readme/openapi-parser@4.1.0
Unpacked Size
214.13 kB
Size
47.16 kB
File Count
9
NPM Version
lerna/8.2.1/node@v20.19.0+arm64 (darwin)
Node Version
20.19.0
Published on
Jun 04, 2025
Total Downloads
Cumulative downloads
Total Downloads
23,854,566
Last Day
-24.2%
17,998
Compared to previous day
Last Week
-8.2%
322,508
Compared to previous week
Last Month
8.4%
1,386,218
Compared to previous month
Last Year
77.1%
13,002,332
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
6
Peer Dependencies
1
Dev Dependencies
5
Comprehensive tooling for working with OpenAPI definitions
oas is the library that we've built at ReadMe for powering everything we do related to OpenAPI; from our Reference Guides, to our Metrics product, or other in-house tooling like code generation, request execution, and SDK code generation.
Installation
npm install oas
Usage
[!NOTE] If you need to use this library within a browser you'll likely need to use a bundler like Webpack or Rollup.
oas offers a main Oas class, which will be your main entrypoint for using the library.
1import Oas from 'oas'; 2import petstoreSpec from '@readme/oas-examples/3.0/json/petstore.json'; 3 4const petstore = new Oas(petstoreSpec);
Here the Oas constructor takes a JSON API definition (petstoreSpec). All API definitions you feed it must be JSON and must be an OpenAPI definition. If you have a YAML or Swagger definition you will need to convert it (our oas-normalize library can do this for you). And if you're in a CJS or non-import environment you can pull the library in with require('oas').default.
From here, the following APIs are at your disposal.
OpenAPI definitions
Because this library has full TypeScript types and docblocks this README is not intended to be full documentation so consult the individual method docblocks if you need more information on a specific method.
General
| Method | Description |
|---|---|
.dereference() | Dereference the current OpenAPI definition. Note that this will ignore circular references. |
.getCircularReferences() | Retrieve an array of any circular $ref pointer that may exist wthin the OpenAPI definition. Note that this requires .dereference() to be called first. |
.getDefinition() | Retrieve the OpenAPI definition that was fed into the Oas constructor. |
.getTags() | Retrieve an array of all tags that exist within the API definition and are set on operations. |
.getPaths() | Retrieve every operation that exists within the API definition. This returns an array of instances of the Operation class. |
.getVersion() | Retrieve the OpenAPI version that this API definition is targeted for. |
.getWebhooks() | Retrieve every webhook operation that exists within the API definition. This returns an array of instances of the Webhook class. |
#init() | An alternative for new Oas() that you can use if the typing on the Oas constructor gives you trouble. Typing OpenAPI definitions is hard! |
Operations
| Method | Description |
|---|---|
.findOperation() | Discover an operation with the current OpenAPI definition that matches a given URL and HTTP method. |
.findOperationWithoutMethod() | Like .findOperation() but without supplying an HTTP method. |
.getOperation() | Same as .findOperation() but this returns an instance of the Operation class. |
.getOperationById() | Retrieve an operation in an OpenAPI definition by an operationId. |
.operation() | Retrieve an instance of the Operation or Webhook classes for a given path and HTTP method. |
Servers
| Method | Description |
|---|---|
.defaultVariables() | Retrieve the default server variables for a specific server URL, while also potentially factoring in user data. You can specify user variable data to the Oas constructor. Check out Using Variables in Documentation for some background on how we use this. |
.replaceUrl() | Replace a given templated server URL with supplied server variable data. |
.splitUrl() | Chunk out a specific server URL into its individual parts. |
.splitVariables | Chunk out a given URL and if it matches a server URL in the OpenAPI file, extract the matched server variables that are present in the URL. |
.url() | Retrieve a fully composed server URL. You can optionally select which of the defined server URLs to use as well as specify server variable information. |
.variables() | Retrieve all server variables that a specific server URL in the definition has. |
Specification Extensions
[!NOTE] Optionally you can also supply an instance of the
Operationto both of these methods to see or retrieve a given extension if it exists on that operation but if it exists in both the operation and at the root the operation-level extension will be prioritized.
| Method | Description |
|---|---|
.getExtension() | Retrieve a given specification extension if it exists at the root of the API definition. |
.hasExtension() | Determine if a given specification extension exists on the root of the API definition. |
.validateExtension() | Determine if a given ReadMe custom OpenAPI extension is valid or not. |
.validateExtensions() | Validate all of our ReadMe custom OpenAPI extension, throwing exceptions when necessary. |
Information about ReadMe's supported OpenAPI extensions at https://docs.readme.com/docs/openapi-extensions.
User Authentication
| Method | Description |
|---|---|
.getAuth() | Retrieve the appropriate API keys for the current OpenAPI definition from an object of user data. Check out Using Variables in Documentation for some background on how we use this. |
Operations
For your convenience, the entrypoint into the Operation class should generally always be through .operation(). For example:
1import Oas from 'oas'; 2import petstoreSpec from '@readme/oas-examples/3.0/json/petstore.json'; 3 4const petstore = new Oas(petstoreSpec); 5const operation = petstore.operation('/pet', 'post');
General
| Method | Description |
|---|---|
.getContentType() | Retrieve the primary request body content type. If multiple are present, prefer whichever is JSON-compliant. |
.getDescription() | Retrieve the description that's set on this operation. This supports common descriptions that may be set at the path item level. |
.getOperationId() | Retrieve the operationId that's present on the operation, and if one is not present one will be created based off the method + path and returned instead. |
.hasOperationId() | Determine if the operation has an operationId present. |
.isDeprecated() | Determine if this operation is marked as deprecated. |
.isFormUrlEncoded() | Determine if this operation requires its payload to be delivered as application/x-www-form-urlencoded. |
.isJson() | Determine if this operation requires its payload to be delivered as JSON. |
.isMultipart() | Determine if this operation requires its data to be sent as a multipart payload. |
.isXml() | Determine if this operation requires its data to be sent as XML. |
.isWebhook() | Determine if this operation is an instance of the Webhook class. |
.getExampleGroups() | Returns an object with groups of all example definitions (body/header/query/path/response/etc.). The examples are grouped by their key when defined via the examples map. |
.getHeaders() | Retrieve all headers that can either be sent for or returned from this operation. This includes header-based authentication schemes, common header parameters, and request body and response content types. |
.getSummary() | Retrieve the summary that's set on this operation. This supports common summaries that may be set at the path item level. |
.getTags() | Retrieve all tags, and their metadata, that exist on this operation. |
Callbacks
| Method | Description |
|---|---|
.getCallback() | Retrieve a specific callback on this operation. This will return an instance of the Callback class. |
.getCallbackExamples() | Retrieve an array of all calback examples that this operation has defined. |
.getCallbacks() | Retrieve all callbacks that this operation has. Similar to .getPaths() returning an array of Operation instances this will return an array of Callback instances. |
.hasCallbacks() | Determine if this operation has any callbacks defined. |
Parameters
[!NOTE] All parameter accessors here support, and will automatically retrieve and handle, common parameters that may be set at the path item level.
| Method | Description |
|---|---|
.getParameters() | Retrieve all parameters that may be used with on this operation. |
.getParametersAsJSONSchema() | Retrieve and convert the operations parameters into an array of JSON Schema schemas for each available type of parameter available on the operation: path, query, body, cookie, formData, and header. |
.hasParameters() | Determine if the operation has any parameters to send. |
.hasRequiredParameters() | Determine if any of the parameters on this operation are required. |
Request Body
| Method | Description |
|---|---|
.getRequestBody() | Retrieve the raw request body object for a given content type. If none is specified it will return either the first that's JSON-like, or the first defined. |
.getRequestBodyExamples() | Retrieve an array of all request body examples that this operation has defined. |
.getRequestBodyMediaTypes() | Retrieve a list of all the media/content types that the operation can accept a request body payload for. |
.hasRequestBody() | Determine if this operation has a request body defined. |
.hasRequiredRequestBody() | Determine if this operation has a required request body. |
Responses
| Method | Description |
|---|---|
.getResponseAsJSONSchema() | Retrive and convert a response on this operation into JSON Schema. |
.getResponseByStatusCode() | Retrieve the raw response object for a given status code. |
.getResponseExamples() | Retrieve an array of all response examples that this operation has defined. |
.getResponseStatusCodes() | Retrieve all status codes that this operation may respond with. |
Security
| Method | Description |
|---|---|
.getSecurity() | Return all security requirements that are applicable for either this operation, or if the operation has none specific to it, then for the entire API. |
.getSecurityWithTypes() | Return a collection of all security schemes applicable to this operation (using .getSecurity()), grouped by how the security should be handled (either AND or OR auth requirements). |
.prepareSecurity | Return an object of every security scheme that can be used on this operation, indexed by the type of security scheme it is (eg. Basic, OAuth2, APIKey, etc.). |
Specification Extensions
| Method | Description |
|---|---|
.hasExtension() | Determine if a given specification extension exists on this operation. |
Information about ReadMe's supported OpenAPI extensions at https://docs.readme.com/docs/openapi-extensions.
Callbacks
The Callback class inherits Operation so every API available on instances of Operation is available here too. Much like Operation, we also support common parameters, summaries, and descriptions that may be set at the path item level within a callbacks definition.
General
| Method | Description |
|---|---|
.getIdentifier() | Retrieve the primary identifier of this callback. |
Webhooks
Because our Webhook class extends Operation, every API that's available on the Operation class is available on webhooks.
Additional Utilities
Beyond the Oas, Operation, Callback and Webhook interfaces, the oas library also offers additional tooling for analyzing and troubleshooting OpenAPI definitions.
Analyzer
The analyzer, oas/analyzer, allows you to run a set of query analyses on your API definition to understand the complexity of your API definition.
1import petstore from '@readme/oas-examples/3.0/json/petstore.json'; 2import analyzer from 'oas/analyzer'; 3 4console.log(await analyzer(petstore));
General
| Metric | Description |
|---|---|
dereferencedFileSize | Size of the definition after resolving all references. |
mediaTypes | What are the different media type shapes that your API operations support? |
operationTotal | The total amount of operations in your definition. |
rawFileSize | Size of the definition in its raw form. |
securityTypes | The different types of security that your API contains. |
OpenAPI Features
| Metric | Description |
|---|---|
additionalProperties | Does your API use additionalProperties? |
callbacks | Does your API use callbacks? |
circularRefs | Does your API have any circular $ref pointers, and if so where are they located? |
commonParameters | Does your API utilize common parameters? |
discriminators | Does your API use polymorphic discriminators? |
links | Does your API use links? |
style | Do any parameters in your API require style serialization? |
polymorphism | Does your API use polymorphism (anyOf, oneOf, allOf)? |
serverVariables | Does your API use server variables? |
webhooks | Does your API use webhooks? |
xml | Does any parameter or schema in your API use the XML object for declaring how a schema should be treated in XML? |
Reducer
[!WARNING] This API is still very experimental and should not be used in production environments!
The reducer, oas/reducer, can be used to reduce an OpenAPI definition down to only the information necessary for a specific set of tags, paths, or operations. OpenAPI reduction can be helpful to isolate and troubleshoot issues with a very large API definition -- all while still having a fully functional and valid OpenAPI definition.
1import petstore from '@readme/oas-examples/3.0/json/petstore.json'; 2import reducer from 'oas/reducer'; 3 4// This will reduce the `petstore` API definition down to only operations, and 5// any referenced schemas, that are a part of the `Store` tag. 6console.log(reducer(petstore, { tags: ['Store'] })); 7 8// Reduces the `petstore` down to only the `POST /pet` operation. 9console.log(reducer(petstore, { paths: { '/pet': ['post'] } }); 10 11// You can also select all of the methods of a given path by using the `*` 12// wildcard. The resulting reduced API definition here will contain `POST /pet` 13// and `PUT /put`. 14console.log(reducer(petstore, { paths: { '/pet': ['*'] } });
[!NOTE] Though the reducer does not require you to first dereference your API definition it currently unfortunately cannot, depending on the circumstances, be used to dereference an API operation that has circular
$refpointers.
FAQ
Can I create an OpenAPI definition with this?
Though oas used to offer functionality related to this, it does no longer. If you need an OpenAPI (or Swagger) definition for your API we recommend checking out the API editing experience within ReadMe, manually maintaining JSON/YAML files (it sounds worse than it actually is), or the language-agnostic swagger-inline.
No vulnerabilities found.
Reason
29 commit(s) and 1 issue activity found in the last 90 days -- score normalized to 10
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
security policy file detected
Details
- Info: security policy file detected: github.com/readmeio/.github/.github/SECURITY.md:1
- Info: Found linked content: github.com/readmeio/.github/.github/SECURITY.md:1
- Info: Found disclosure, vulnerability, and/or timelines in security policy: github.com/readmeio/.github/.github/SECURITY.md:1
- Info: Found text in security policy: github.com/readmeio/.github/.github/SECURITY.md:1
Reason
SAST tool is run on all commits
Details
- Info: SAST configuration detected: CodeQL
- Info: all commits (16) are checked with a SAST tool
Reason
1 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw
Reason
Found 7/24 approved changesets -- score normalized to 2
Reason
dependency not pinned by hash detected -- score normalized to 2
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/ci.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:26: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/ci.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:43: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/ci.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:44: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/ci.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:54: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/ci.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:55: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/ci.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/codeql-analysis.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:30: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/codeql-analysis.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:35: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/codeql-analysis.yml/main?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/lint-pr-title.yaml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/lint-pr-title.yaml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/sync.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/sync.yml/main?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/sync.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/sync.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/validate.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/validate.yml/main?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/validate.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/validate.yml/main?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/validate.yml:29: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/validate.yml/main?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/validate.yml:34: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/validate.yml/main?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/validate.yml:39: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/validate.yml/main?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/validate.yml:44: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/validate.yml/main?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/validate.yml:49: update your workflow using https://app.stepsecurity.io/secureworkflow/readmeio/oas/validate.yml/main?enable=pin
- Info: 0 out of 11 GitHub-owned GitHubAction dependencies pinned
- Info: 0 out of 8 third-party GitHubAction dependencies pinned
- Info: 3 out of 3 npmCommand dependencies pinned
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Info: jobLevel 'actions' permission set to 'read': .github/workflows/codeql-analysis.yml:16
- Info: jobLevel 'contents' permission set to 'read': .github/workflows/codeql-analysis.yml:17
- Warn: no topLevel permission defined: .github/workflows/ci.yml:1
- Warn: no topLevel permission defined: .github/workflows/codeql-analysis.yml:1
- Info: topLevel 'pull-requests' permission set to 'read': .github/workflows/lint-pr-title.yaml:10
- Warn: no topLevel permission defined: .github/workflows/sync.yml:1
- Warn: no topLevel permission defined: .github/workflows/validate.yml:1
- Info: no jobLevel write permissions found
Reason
license file not detected
Details
- Warn: project does not have a license file
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Score
6.1
/10
Last Scanned on 2025-06-23
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More