New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

openapi-typescript

Package Overview
Dependencies
Maintainers
1
Versions
145
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

openapi-typescript - npm Package Compare versions

Comparing version 2.4.2 to 3.0.0-rc.0

53

bin/cli.js
#!/usr/bin/env node
const fs = require("fs");
const chalk = require("chalk");
const { bold, green, red } = require("kleur");
const path = require("path");

@@ -16,3 +16,3 @@ const meow = require("meow");

--help display this
--output, -o specify output file
--output, -o (optional) specify output file (default: stdout)
--prettier-config (optional) specify path to Prettier config file

@@ -41,18 +41,25 @@ --raw-schema (optional) Read from raw schema instead of document

console.info(
chalk.bold(`✨ openapi-typescript ${require("../package.json").version}`)
);
const pathToSpec = cli.input[0];
const timeStart = process.hrtime();
(async () => {
let spec = "";
async function main() {
let output = "FILE"; // FILE or STDOUT
const pathToSpec = cli.input[0];
// 0. setup
if (!cli.flags.output) {
output = "STDOUT"; // if --output not specified, fall back to stdout
}
if (output === "FILE") {
console.info(bold(`✨ openapi-typescript ${require("../package.json").version}`)); // only log if we’re NOT writing to stdout
}
// 1. input
let spec = undefined;
try {
spec = await loadSpec(pathToSpec);
} catch (e) {
console.error(chalk.red(`❌ "${e}"`));
return;
spec = await loadSpec(pathToSpec, { log: output !== "STDOUT" });
} catch (err) {
throw new Error(red(`❌ ${err}`));
}
// 2. generate schema (the main part!)
const result = swaggerToTS(spec, {

@@ -64,4 +71,5 @@ prettierConfig: cli.flags.prettierConfig,

// Write to file if specifying output
if (cli.flags.output) {
// 3. output
if (output === "FILE") {
// output option 1: file
const outputFile = path.resolve(process.cwd(), cli.flags.output);

@@ -82,12 +90,11 @@

const time = timeEnd[0] + Math.round(timeEnd[1] / 1e6);
console.log(
chalk.green(
`🚀 ${cli.input[0]} -> ${chalk.bold(cli.flags.output)} [${time}ms]`
)
);
return;
console.log(green(`🚀 ${pathToSpec} -> ${bold(cli.flags.output)} [${time}ms]`));
} else {
// output option 2: stdout
process.stdout.write(result);
}
// Otherwise, return result
return result;
})();
}
main();

29

bin/loaders/index.js
const yaml = require("js-yaml");
const chalk = require("chalk");
const { bold, yellow } = require("kleur");

@@ -8,16 +8,19 @@ const loadFromFs = require("./loadFromFs");

async function load(pathToSpec) {
let rawSpec;
// option 1: remote URL
if (/^https?:\/\//.test(pathToSpec)) {
try {
rawSpec = await loadFromHttp(pathToSpec);
const rawSpec = await loadFromHttp(pathToSpec);
return rawSpec;
} catch (e) {
if (e.code === 'ENOTFOUND') {
throw new Error(`The URL ${pathToSpec} could not be reached. Ensure the URL is correct, that you're connected to the internet and that the URL is reachable via a browser.`)
if (e.code === "ENOTFOUND") {
throw new Error(
`The URL ${pathToSpec} could not be reached. Ensure the URL is correct, that you're connected to the internet and that the URL is reachable via a browser.`
);
}
throw e;
}
} else {
rawSpec = await loadFromFs(pathToSpec);
}
return rawSpec;
// option 2: local file
return loadFromFs(pathToSpec);
}

@@ -29,4 +32,6 @@

module.exports.loadSpec = async (pathToSpec) => {
console.log(chalk.yellow(`🤞 Loading spec from ${chalk.bold(pathToSpec)}…`));
module.exports.loadSpec = async (pathToSpec, { log = true }) => {
if (log === true) {
console.log(yellow(`🤞 Loading spec from ${bold(pathToSpec)}…`)); // only log if not writing to stdout
}
const rawSpec = await load(pathToSpec);

@@ -51,6 +56,4 @@

} catch {
throw new Error(
`The spec under ${pathToSpec} couldn’t be parsed neither as YAML nor JSON.`
);
throw new Error(`The spec under ${pathToSpec} couldn’t be parsed neither as YAML nor JSON.`);
}
};

17

bin/loaders/loadFromFs.js

@@ -8,14 +8,7 @@ const fs = require("fs");

return new Promise((resolve, reject) => {
if (pathExists) {
fs.readFile(pathname, "UTF-8", (err, data) => {
if (err) {
reject(err);
}
resolve(data);
});
} else {
reject(`Cannot find spec under the following path: ${pathname}`);
}
});
if (!pathExists) {
throw new Error(`Cannot find spec under the following path: ${pathname}`);
}
return fs.readFileSync(pathname, "utf8");
};

23

dist-node/index.js

@@ -153,2 +153,5 @@ 'use strict';

}
function isOpenAPI2Reference(additionalProperties) {
return additionalProperties.$ref !== undefined;
}

@@ -212,2 +215,10 @@ function propertyMapper(schema, transform) {

function getAdditionalPropertiesType(additionalProperties) {
if (isOpenAPI2Reference(additionalProperties)) {
return transformRef(additionalProperties.$ref, rawSchema ? "definitions/" : "");
}
return nodeType(additionalProperties);
}
function transform(node) {

@@ -241,3 +252,3 @@ switch (nodeType(node)) {

if (node.additionalProperties) {
properties += `[key: string]: ${nodeType(node.additionalProperties) || "any"};\n`;
properties += `[key: string]: ${getAdditionalPropertiesType(node.additionalProperties) || "any"};\n`;
}

@@ -431,12 +442,14 @@

output += `responses: {\n`;
Object.entries(operation.responses).forEach(([statusCode, response]) => {
Object.entries(operation.responses).forEach(([statusCodeString, response]) => {
const statusCode = Number(statusCodeString) || statusCodeString;
if (!response) return;
if (response.description) output += comment(response.description);
if (!response.content || !Object.keys(response.content).length) {
const type = statusCode === "204" || Math.floor(+statusCode / 100) === 3 ? "never" : "unknown";
output += `"${statusCode}": ${type};\n`;
const type = statusCode === 204 || Math.floor(+statusCode / 100) === 3 ? "never" : "unknown";
output += `${statusCode}: ${type};\n`;
return;
}
output += `"${statusCode}": {\n`;
output += `${statusCode}: {\n`;
Object.entries(response.content).forEach(([contentType, encodedResponse]) => {

@@ -443,0 +456,0 @@ output += `"${contentType}": ${transform(encodedResponse.schema)};\n`;

3

dist-src/index.js

@@ -14,4 +14,3 @@ import path from "path";

export default function swaggerToTS(schema, options) {
const version = (options && options.version) ||
swaggerVersion(schema);
const version = (options && options.version) || swaggerVersion(schema);
let output = `${WARNING_MESSAGE}`;

@@ -18,0 +17,0 @@ switch (version) {

3

dist-src/utils.js

@@ -77,1 +77,4 @@ export function comment(text) {

}
export function isOpenAPI2Reference(additionalProperties) {
return additionalProperties.$ref !== undefined;
}

22

dist-src/v2.js
import propertyMapper from "./property-mapper";
import { comment, nodeType, transformRef, tsArrayOf, tsIntersectionOf, tsUnionOf, } from "./utils";
import { comment, nodeType, transformRef, tsArrayOf, tsIntersectionOf, tsUnionOf, isOpenAPI2Reference } from "./utils";
export const PRIMITIVES = {

@@ -29,5 +29,9 @@ boolean: "boolean",

}
const propertyMapped = options
? propertyMapper(definitions, options.propertyMapper)
: definitions;
const propertyMapped = options ? propertyMapper(definitions, options.propertyMapper) : definitions;
function getAdditionalPropertiesType(additionalProperties) {
if (isOpenAPI2Reference(additionalProperties)) {
return transformRef(additionalProperties.$ref, rawSchema ? "definitions/" : "");
}
return nodeType(additionalProperties);
}
function transform(node) {

@@ -44,10 +48,6 @@ switch (nodeType(node)) {

case "enum": {
return tsUnionOf(node.enum.map((item) => typeof item === "number" || typeof item === "boolean"
? item
: `'${item}'`));
return tsUnionOf(node.enum.map((item) => typeof item === "number" || typeof item === "boolean" ? item : `'${item}'`));
}
case "object": {
if ((!node.properties || !Object.keys(node.properties).length) &&
!node.allOf &&
!node.additionalProperties) {
if ((!node.properties || !Object.keys(node.properties).length) && !node.allOf && !node.additionalProperties) {
return `{ [key: string]: any }`;

@@ -57,3 +57,3 @@ }

if (node.additionalProperties) {
properties += `[key: string]: ${nodeType(node.additionalProperties) || "any"};\n`;
properties += `[key: string]: ${getAdditionalPropertiesType(node.additionalProperties) || "any"};\n`;
}

@@ -60,0 +60,0 @@ return tsIntersectionOf([

40

dist-src/v3.js

@@ -21,5 +21,3 @@ import propertyMapper from "./property-mapper";

const operations = {};
const propertyMapped = options
? propertyMapper(components.schemas, options.propertyMapper)
: components.schemas;
const propertyMapped = options ? propertyMapper(components.schemas, options.propertyMapper) : components.schemas;
function transform(node) {

@@ -36,5 +34,3 @@ switch (nodeType(node)) {

case "enum": {
return tsUnionOf(node.enum.map((item) => typeof item === "number" || typeof item === "boolean"
? item
: `'${item.replace(/'/g, "\\'")}'`));
return tsUnionOf(node.enum.map((item) => typeof item === "number" || typeof item === "boolean" ? item : `'${item.replace(/'/g, "\\'")}'`));
}

@@ -48,5 +44,3 @@ case "oneOf": {

case "object": {
if ((!node.properties || !Object.keys(node.properties).length) &&
!node.allOf &&
!node.additionalProperties) {
if ((!node.properties || !Object.keys(node.properties).length) && !node.allOf && !node.additionalProperties) {
return `{ [key: string]: any }`;

@@ -57,5 +51,3 @@ }

? [
`{ [key: string]: ${node.additionalProperties === true
? "any"
: transform(node.additionalProperties) || "any"};}\n`,
`{ [key: string]: ${node.additionalProperties === true ? "any" : transform(node.additionalProperties) || "any"};}\n`,
]

@@ -148,13 +140,14 @@ : [];

output += `responses: {\n`;
Object.entries(operation.responses).forEach(([statusCode, response]) => {
Object.entries(operation.responses).forEach(([statusCodeString, response]) => {
const statusCode = Number(statusCodeString) || statusCodeString;
if (!response)
return;
if (response.description)
output += comment(response.description);
if (!response.content || !Object.keys(response.content).length) {
const type = statusCode === "204" || Math.floor(+statusCode / 100) === 3
? "never"
: "unknown";
output += `"${statusCode}": ${type};\n`;
const type = statusCode === 204 || Math.floor(+statusCode / 100) === 3 ? "never" : "unknown";
output += `${statusCode}: ${type};\n`;
return;
}
output += `"${statusCode}": {\n`;
output += `${statusCode}: {\n`;
Object.entries(response.content).forEach(([contentType, encodedResponse]) => {

@@ -174,12 +167,3 @@ output += `"${contentType}": ${transform(encodedResponse.schema)};\n`;

Object.entries(pathItem).forEach(([field, operation]) => {
const isMethod = [
"get",
"put",
"post",
"delete",
"options",
"head",
"patch",
"trace",
].includes(field);
const isMethod = ["get", "put", "post", "delete", "options", "head", "patch", "trace"].includes(field);
if (isMethod) {

@@ -186,0 +170,0 @@ operation = operation;

3

dist-types/types/OpenAPI3.d.ts

@@ -28,3 +28,4 @@ export interface OpenAPI3Schemas {

responses: {
[statusCode: string]: OpenAPI3ResponseObject;
[statusCode: number]: OpenAPI3ResponseObject;
default?: OpenAPI3ResponseObject;
};

@@ -31,0 +32,0 @@ }

3

dist-types/utils.d.ts

@@ -1,2 +0,2 @@

import { OpenAPI2, OpenAPI3 } from "./types";
import { OpenAPI2, OpenAPI2Reference, OpenAPI2SchemaObject, OpenAPI3 } from "./types";
export declare function comment(text: string): string;

@@ -14,2 +14,3 @@ export declare function fromEntries(entries: [string, any][]): Record<string, unknown>;

export declare function unrefComponent(components: any, ref: string): any;
export declare function isOpenAPI2Reference(additionalProperties: OpenAPI2SchemaObject | OpenAPI2Reference | boolean): additionalProperties is OpenAPI2Reference;
export {};

8

package.json
{
"name": "openapi-typescript",
"description": "Generate TypeScript types from Swagger OpenAPI specs",
"version": "2.4.2",
"version": "3.0.0-rc.0",
"license": "ISC",

@@ -36,6 +36,6 @@ "bin": {

"dependencies": {
"chalk": "^4.1.0",
"js-yaml": "^3.14.0",
"kleur": "^3.0.3",
"meow": "^8.0.0",
"prettier": "^2.1.2"
"prettier": "^2.2.0"
},

@@ -57,3 +57,3 @@ "devDependencies": {

"ts-jest": "^26.4.1",
"typescript": "^4.0.3"
"typescript": "^4.1.2"
},

@@ -60,0 +60,0 @@ "engines": {

174

README.md

@@ -5,3 +5,5 @@ [![version(scoped)](https://img.shields.io/npm/v/openapi-typescript.svg)](https://www.npmjs.com/package/openapi-typescript)

<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
[![All Contributors](https://img.shields.io/badge/all_contributors-23-orange.svg?style=flat-square)](#contributors-)
[![All Contributors](https://img.shields.io/badge/all_contributors-24-orange.svg?style=flat-square)](#contributors-)
<!-- ALL-CONTRIBUTORS-BADGE:END -->

@@ -11,3 +13,3 @@

🚀 Convert [OpenAPI 3.0][openapi3] and [OpenAPI 2.0 (Swagger)][openapi2] schemas to TypeScript interfaces using Node.js.
🚀 Convert [OpenAPI 3.0][openapi3] and [2.0 (Swagger)][openapi2] schemas to TypeScript interfaces using Node.js.

@@ -47,5 +49,12 @@ 💅 The output is prettified with [Prettier][prettier] (and can be customized!).

#### Outputting to `stdout`
```bash
npx openapi-typescript schema.yaml
```
#### Generating multiple schemas
In your `package.json`, for each schema you’d like to transform add one `generate:specs:[name]` npm-script. Then combine them all into one `generate:specs` script, like so:
In your `package.json`, for each schema you’d like to transform add one `generate:specs:[name]` npm-script. Then combine
them all into one `generate:specs` script, like so:

@@ -61,2 +70,9 @@ ```json

If you use [npm-run-all][npm-run-all], you can shorten this:
```json
"scripts": {
"generate:specs": "run-p generate:specs:*",
```
You can even specify unique options per-spec, if needed. To generate them all together, run:

@@ -93,17 +109,16 @@

The Node API is a bit more flexible: it will only take a JS object as input (OpenAPI format), and
return a string of TS definitions. This lets you pull from any source (a Swagger server, local
files, etc.), and similarly lets you parse, post-process, and save the output anywhere.
The Node API is a bit more flexible: it will only take a JS object as input (OpenAPI format), and return a string of TS
definitions. This lets you pull from any source (a Swagger server, local files, etc.), and similarly lets you parse,
post-process, and save the output anywhere.
If your specs are in YAML, you’ll have to convert them to JS objects using a library such as
[js-yaml][js-yaml]. If you’re batching large folders of specs, [glob][glob] may also come in handy.
If your specs are in YAML, you’ll have to convert them to JS objects using a library such as [js-yaml][js-yaml]. If
you’re batching large folders of specs, [glob][glob] may also come in handy.
#### PropertyMapper
In order to allow more control over how properties are parsed, and to specifically handle
`x-something`-properties, the `propertyMapper` option may be specified as the optional 2nd
parameter.
In order to allow more control over how properties are parsed, and to specifically handle `x-something`-properties, the
`propertyMapper` option may be specified as the optional 2nd parameter.
This is a function that, if specified, is called for each property and allows you to change how
openapi-typescript handles parsing of Swagger files.
This is a function that, if specified, is called for each property and allows you to change how openapi-typescript
handles parsing of Swagger files.

@@ -131,128 +146,28 @@ An example on how to use the `x-nullable` property to control if a property is optional:

## Upgrading from v1 to v2
## Migrating from v1 to v2
Some options were removed in openapi-typescript v2 that will break apps using v1, but it does so in exchange for more control, more stability, and more resilient types.
[Migrating from v1 to v2](./docs/migrating-from-v1.md)
TL;DR:
## Project Goals
```diff
-import { OpenAPI2 } from './generated';
+import { definitions } from './generated';
1. Support converting any OpenAPI 3.0 or 2.0 (Swagger) schema to TypeScript types, no matter how complicated
1. The generated TypeScript types **must** match your schema as closely as possible (i.e. don’t convert names to
`PascalCase` or follow any TypeScript-isms; faithfully reproduce your schema as closely as possible, capitalization
and all)
1. This library is a TypeScript generator, not a schema validator.
-type MyType = OpenAPI2.MyType;
+type MyType = definitions['MyType'];
```
## Contributing
#### In-depth explanation
PRs are welcome! Please see our [CONTRIBUTING.md](./CONTRIBUTING.md) guide. Opening an issue beforehand to discuss is
encouraged but not required.
In order to explain the change, let’s go through an example with the following Swagger definition (partial):
```yaml
swagger: 2.0
definitions:
user:
type: object
properties:
role:
type: object
properties:
access:
enum:
- admin
- user
user_role:
type: object
role:
type: string
team:
type: object
properties:
users:
type: array
items:
$ref: user
```
This is how **v1** would have generated those types:
```ts
declare namespace OpenAPI2 {
export interface User {
role?: UserRole;
}
export interface UserRole {
access?: "admin" | "user";
}
export interface UserRole {
role?: string;
}
export interface Team {
users?: User[];
}
}
```
Uh oh. It tried to be intelligent, and keep interfaces shallow by transforming `user.role` into `UserRole.` However, we also have another `user_role` entry that has a conflicting `UserRole` interface. This is not what we want.
v1 of this project made certain assumptions about your schema that don’t always hold true. This is how **v2** generates types from that same schema:
```ts
export interface definitions {
user: {
role?: {
access?: "admin" | "user";
};
};
user_role: {
role?: string;
};
team: {
users?: definitions["user"][];
};
}
```
This matches your schema more accurately, and doesn’t try to be clever by keeping things shallow. It’s also more predictable, with the generated types matching your schema naming. In your code here’s what would change:
```diff
-UserRole
+definitions['user']['role'];
```
While this is a change, it’s more predictable. Now you don’t have to guess what `user_role` was renamed to; you simply chain your type from the Swagger definition you‘re used to.
#### Better \$ref generation
openapi-typescript v1 would attempt to resolve and flatten `$ref`s. This was bad because it would break on circular references (which both Swagger and TypeScript allow), and resolution also slowed it down.
In v2, your `$ref`s are preserved as-declared, and TypeScript does all the work. Now the responsibility is on your schema to handle collisions rather than openapi-typescript, which is a better approach in general.
#### No Wrappers
The `--wrapper` CLI flag was removed because it was awkward having to manage part of your TypeScript definition in a CLI flag. In v2, simply compose the wrapper yourself however you’d like in TypeScript:
```ts
import { components as Schema1 } from './generated/schema-1.ts';
import { components as Schema2 } from './generated/schema-2.ts';
declare namespace OpenAPI3 {
export Schema1;
export Schema2;
}
```
#### No CamelCasing
The `--camelcase` flag was removed because it would mangle object names incorrectly or break trying to sanitize them (for example, you couldn’t run camelcase on a schema with `my.obj` and `my-obj`—they both would transfom to the same thing causing unexpected results).
OpenAPI allows for far more flexibility in naming schema objects than JavaScript, so that should be carried over from your schema. In v2, the naming of generated types maps 1:1 with your schema name.
[glob]: https://www.npmjs.com/package/glob
[js-yaml]: https://www.npmjs.com/package/js-yaml
[openapi2]: https://swagger.io/specification/v2/
[namespace]: https://www.typescriptlang.org/docs/handbook/namespaces.html
[npm-run-all]: https://www.npmjs.com/package/npm-run-all
[openapi3]: https://swagger.io/specification
[namespace]: https://www.typescriptlang.org/docs/handbook/namespaces.html
[prettier]: https://npmjs.com/prettier
## Contributors ✨
### Contributors ✨

@@ -295,2 +210,3 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

<td align="center"><a href="https://massaioli.wordpress.com"><img src="https://avatars3.githubusercontent.com/u/149178?v=4" width="100px;" alt=""/><br /><sub><b>Robert Massaioli</b></sub></a><br /><a href="https://github.com/drwpow/openapi-typescript/commits?author=robertmassaioli" title="Code">💻</a> <a href="https://github.com/drwpow/openapi-typescript/issues?q=author%3Arobertmassaioli" title="Bug reports">🐛</a></td>
<td align="center"><a href="http://jankuca.com"><img src="https://avatars3.githubusercontent.com/u/367262?v=4" width="100px;" alt=""/><br /><sub><b>Jan Kuča</b></sub></a><br /><a href="https://github.com/drwpow/openapi-typescript/commits?author=jankuca" title="Code">💻</a> <a href="https://github.com/drwpow/openapi-typescript/commits?author=jankuca" title="Tests">⚠️</a></td>
</tr>

@@ -301,4 +217,6 @@ </table>

<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.
Contributions of any kind welcome!
dist-node/index.js.map

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc