swagger-typescript-api

What is swagger-typescript-api?

The swagger-typescript-api npm package is a tool that generates TypeScript API client code from Swagger/OpenAPI definitions. It helps developers to create strongly-typed API clients, reducing the risk of runtime errors and improving the development experience.

What are swagger-typescript-api's main functionalities?

Generate TypeScript API Client

This feature allows you to generate a TypeScript API client from a Swagger/OpenAPI definition. The `generateApi` function takes an object with configuration options such as the name of the output file, the URL of the Swagger definition, and the output directory.

const { generateApi } = require('swagger-typescript-api');

generateApi({
  name: 'MyApi.ts',
  url: 'http://api.example.com/swagger.json',
  output: './src/api',
});

Custom Templates

This feature allows you to use custom templates for generating the TypeScript API client. By specifying the `templates` option, you can provide a path to your custom templates, giving you full control over the generated code's structure and style.

const { generateApi } = require('swagger-typescript-api');

generateApi({
  name: 'MyApi.ts',
  url: 'http://api.example.com/swagger.json',
  output: './src/api',
  templates: './my-custom-templates',
});

Generate API Client from Local File

This feature allows you to generate a TypeScript API client from a local Swagger/OpenAPI definition file. The `input` option specifies the path to the local Swagger file.

const { generateApi } = require('swagger-typescript-api');

generateApi({
  name: 'MyApi.ts',
  input: './swagger.json',
  output: './src/api',
});

Other packages similar to swagger-typescript-api

swagger-codegen

The swagger-codegen package is a tool that generates client libraries, server stubs, and API documentation from Swagger/OpenAPI definitions. It supports multiple languages and frameworks. While it is similar to swagger-typescript-api, it is more mature and widely used but may not be as focused on TypeScript-specific features.

typescript-fetch

The typescript-fetch package is a TypeScript client generator for OpenAPI/Swagger definitions that uses the Fetch API. It is similar to swagger-typescript-api in that it generates TypeScript clients, but it specifically targets the Fetch API for making HTTP requests.

README

swagger-typescript-api

Generate api via swagger scheme.
Supports OA 3.0, 2.0, JSON, yaml
Generated api module use Fetch Api to make requests.

Any questions you can ask here or in our slack(#swagger-typescript-api channel)

👀 Examples

All examples you can find here

🛑 It is new version with ETA templates

Version with mustache templates is >4.0.0

📄 Usage

Usage: sta [options]
Usage: swagger-typescript-api [options]

Options:
  -v, --version                 output the current version
  -p, --path <path>             path/url to swagger scheme
  -o, --output <output>         output path of typescript api file (default: "./")
  -n, --name <name>             name of output typescript api file (default: "Api.ts")
  -t, --templates <path>        path to folder containing templates
  -d, --default-as-success      use "default" response status code as success response too.
                                some swagger schemas use "default" response status code
                                as success response type by default. (default: false)
  -r, --responses               generate additional information about request responses
                                also add typings for bad responses (default: false)
  --union-enums                 generate all "enum" types as union types (T1 | T2 | TN) (default: false)
  --route-types                 generate type definitions for API routes (default: false)
  --no-client                   do not generate an API class
  --enum-names-as-values        use values in 'x-enumNames' as enum values (not only as keys) (default: false)
  --js                          generate js api module with declaration file (default: false)
  --extract-request-params      extract request params to data contract (default: false)
                                Also combine path params and query params into one object
  --module-name-index <number>  determines which path index should be used for routes separation (default: 0)
                                (example: GET:/fruites/getFruit -> index:0 -> moduleName -> fruites)
  --modular                     generate separated files for http client, data contracts, and routes (default: false)
  -h, --help                    display help for command

Also you can use npx:

 npx swagger-typescript-api -p ./swagger.json -o ./src -n myApi.ts

You can use this package from nodejs:

const { generateApi } = require('swagger-typescript-api');

// example with url  
generateApi({
  name: "MySuperbApi.ts", // name of output typescript file
  url: 'http://api.com/swagger.json', // url where located swagger schema
})
  .then(({ files, configuration }) => {
    files.forEach(({ content, name }) => {
      fs.writeFile(path, content);
    });
  })
  .catch(e => console.error(e))

// example with local file  
generateApi({
  name: "ApiModule.ts", // name of output typescript file
  input: resolve(process.cwd(), './foo/swagger.json') // path to swagger schema
})
  .then(({ files, configuration }) => {
    files.forEach(({ content, name }) => {
      fs.writeFile(path, content);
    });
  })
  .catch(e => console.error(e))

// example with parsed schema  
generateApi({
  name: "ApiModule.ts", // name of output typescript file
  spec: {
    swagger: "2.0",
    info: {
      version: "1.0.0",
      title: "Swagger Petstore",
    },
    host: "petstore.swagger.io",
    basePath: "/api",
    schemes: ["http"],
    consumes: ["application/json"],
    produces: ["application/json"],
    paths: {
      // ...
    }
    // ...
  }
})
  .then(({ files, configuration }) => {
    files.forEach(({ content, name }) => {
      fs.writeFile(path, content);
    });
  })
  .catch(e => console.error(e))

💎 options

--templates

This option needed for cases when you don't want to use default swagger-typescript-api output structure

Templates:

• api.eta - Api class module
• data-contracts.eta - all types (data contracts) from swagger schema
• http-client.eta - HttpClient class module
• procedure-call.eta - route in Api class
• route-docs.eta - documentation for route in Api class
• route-name.eta - route name for route in Api class
• route-type.eta - (--route-types option)
• route-types.eta - (--route-types option)

How to use it:

• copy swagger-typescript-api templates into your place in project
  • from /templates/default for single api file
  • from /templates/modular for multiple api files (with --modular option)
• add --templates PATH_TO_YOUR_TEMPLATES option
• modify ETA templates as you like

--module-name-index

This option should be used in cases when you have api with one global prefix like /api
Example:
GET:/api/fruits/getFruits
POST:/api/fruits/addFruits
GET:/api/vegetables/addVegetable
with --module-name-index 0 Api class will have one property api
When we change it to --module-name-index 1 then Api class have two properties fruits and vegetables

📄 Mass media

• Why Swagger schemes are needed in frontend development ?
• Migration en douceur vers TypeScript

🚀 How it looks

🛠️ Contribution

❗❗❗ Please use the next branch :)

If you need to check your changes at schemas in tests folder before create a PR just run command npm run test:all

📝 License

Licensed under the MIT License.