swagger-axios-codegen

Introduction to swagger-axios-codegen

swagger-axios-codegen is a project designed to make it easier for developers to generate Swagger clients utilizing Axios and TypeScript. It provides a convenient and efficient way to interact with REST APIs by leveraging Swagger/OpenAPI specifications to automatically produce client-side code.

Key Features

• TypeScript and Axios Integration: swagger-axios-codegen creates code that combines TypeScript's type-checking capabilities with Axios's promise-based HTTP client.
• Promise Handling: It resolves axios.response.data with a promise or rejects it with axios.error.
• Library Support: Although it primarily uses Axios, it can support other libraries like Fly.js with some configuration adjustments.
• TypeScript Output: The output client code utilizes ES6 and TypeScript for modern and reliable software development practices.

Getting Started

To start using swagger-axios-codegen, you need to install it using Yarn:

yarn add swagger-axios-codegen

Configuration Options

swagger-axios-codegen offers multiple configuration options via the ISwaggerOptions interface:

• serviceNameSuffix: Adds a suffix to service names.
• enumNamePrefix: Specifies a prefix for enums.
• methodNameMode: Configures how method names are generated, with options like 'operationId', 'path', or custom functions.
• outputDir & fileName: Determine where the generated files are stored and their naming conventions.
• useStaticMethod: Allows the use of static methods for service interaction.
• useCustomerRequestInstance: Enables the use of a custom request library or instance.

Using Local or Remote Swagger API

You can generate code based on a local swagger JSON file:

const { codegen } = require('swagger-axios-codegen')
codegen({
  methodNameMode: 'operationId',
  source: require('./swagger.json')
})

Or use a remote Swagger JSON URL:

const { codegen } = require('swagger-axios-codegen')
codegen({
  methodNameMode: 'operationId',
  remoteUrl:'Your remote URL'
})

Static Methods and Custom Instances

The option to use static methods simplifies how the service is invoked:

codegen({
    methodNameMode: 'operationId',
    remoteUrl: 'http://localhost:22742/swagger/v1/swagger.json',
    outputDir: '.',
    useStaticMethod: true
});

Create instances using custom Axios configurations as needed:

import axios from 'axios'
import { serviceOptions } from './service'
const instance = axios.create({
  baseURL: 'https://some-domain.com/api/',
  timeout: 1000,
  headers: {'X-Custom-Header': 'foobar'}
});

serviceOptions.axios = instance

Custom Transformations and Validations

swagger-axios-codegen also supports advanced features like date transformation using class-transformer and validation models to ensure data integrity according to Swagger definitions.

Example with class-transformer:

const { codegen } = require('swagger-axios-codegen')
codegen({
  methodNameMode: 'operationId',
  source: require('./swagger.json'),
  useClassTransformer: true,
})

Validation model example:

codegen({
    modelMode: 'class',
    generateValidationModel: true
});

Special Solutions and Use Cases

swagger-axios-codegen supports specific scenarios such as handling reference parameters and integration with microservice gateways, making it a versatile choice for a range of projects.

Conclusion

swagger-axios-codegen is a valuable tool for developers looking to streamline their client-side code generation, enhancing productivity and accuracy in API client implementations. With its support for modern languages and practices, it's a solid choice for contemporary web development projects.