DOCSEARCHbyAlgolia
Submit Docs

Swagger Client

repository·master·Indexed 25 days ago

https://github.com/swagger-api/swagger-js

A JavaScript library (npm: swagger-client) for fetching, resolving, and interacting with Swagger 2.0 and OpenAPI 3 specifications. It provides an OpenAPI Definition Resolver, an HTTP client for OAS operations, and a Tags Interface. Version 3.x requires Node.js >=22 or modern browsers and utilizes a Promise-based pattern for initialization and API execution.

Tokens
12.9K
Snippets
28
Records
88
Agent score
83%

What's inside swagger-client

  1. Overview of Swagger Client

    master

    Swagger Client is a JavaScript module designed to fetch, resolve, and interact with Swagger/OpenAPI documents.

    Note that while the GitHub repository is named swagger-js, the npm package is named swagger-client. The current 3.x version supports both Swagger 2.0 and OpenAPI 3 specifications.

  2. Migrate from swagger-client 2.x to 3.x

    master

    When upgrading from version 2.x to 3.x, several breaking changes must be addressed:

    1. Specification Support: Versions 1.0, 1.1, and 1.2 of the Swagger specification are no longer supported. You must use OAS 2.0 or higher.
    2. Promises vs Callbacks: The library has moved from a callback-based pattern to a Promise-based pattern. Creating a SwaggerClient instance now returns a Promise.
    3. API Access via client.apis: You can no longer access tags directly on the client object. All operations must be accessed through the client.apis object.
    4. Response Body Key: The key for the parsed response body in response payloads has changed from obj to body.
    5. Default Content-Type: The client no longer automatically assumes Content-Type: application/json if no consumes values are provided. You may need to use a requestInterceptor to restore this behavior.

  8. Use the Tags Interface to call OAS operations

    master

    The Tags Interface transforms OpenAPI Specification (OAS) operationIds into callable JavaScript functions. Each function returns a Promise that resolves to a Response.

    How operations are mapped to function names:

    • With operationId: The operationId is used directly.
    • Without operationId: A name is deduced from the HTTP method and path (e.g., ${method}${pathName}), with non-alphanumeric characters replaced by _.
    • Missing Tags: If an operation has no tag, it is grouped under the default tag in the client.apis object.
    • Duplicate operationIds: If IDs are duplicated, they are renamed with numbers (e.g., operation1, operation2) to ensure uniqueness.
    import SwaggerClient from 'swagger-client';

// Example: Calling an operation with an operationId
new SwaggerClient({ spec })
  .then(client => client.apis.default.getUserById(...));

// Example: Calling a deduced operation (method + path)
new SwaggerClient({ spec })
  .then(client => client.apis.default.getOne(...));

  10. Instantiate SwaggerClient

    master

    You can use SwaggerClient either by explicitly calling the constructor with new or by calling it as a function. Calling it as a function implicitly instantiates the constructor for you. Both methods accept a URL to an OpenAPI 2.0 or OpenAPI 3 specification.

    import SwaggerClient from 'swagger-client';

// Explicit instantiation
new SwaggerClient('http://petstore.swagger.io/v2/swagger.json');

// Implicit instantiation (calling as a function)
SwaggerClient('http://petstore.swagger.io/v2/swagger.json');
    import SwaggerClient from 'swagger-client';

new SwaggerClient('http://petstore.swagger.io/v2/swagger.json');
SwaggerClient('http://petstore.swagger.io/v2/swagger.json');

  11. Test swagger-js changes in Swagger-UI

    master

    To test local changes made in swagger-js within a running instance of swagger-ui, follow these steps:

    1. Clone and install swagger-ui: Follow the setup instructions in the swagger-ui repository.
    2. Clone and install swagger-js: Follow the standard setup steps for swagger-js.
    3. Link repositories: Use npm link to connect the local swagger-client to swagger-ui.
    4. Disable predev script: In swagger-ui/package.json, temporarily delete the line "predev": "npm install" to prevent npm from overwriting your linked version during development.
    5. Run development server: Start swagger-ui using npm run dev.
    6. Cleanup: After testing, restore the "predev": "npm install" line in swagger-ui/package.json, unlink the packages, and reinstall dependencies.
    # 1. Link swagger-js to your system
$ cd /path/to/swagger-js
$ npm run build
$ npm link

# 2. Link swagger-client to swagger-ui
$ cd /path/to/swagger-ui
$ npm link swagger-client

# 3. (Manual Step) Remove "predev": "npm install" from swagger-ui/package.json

# 4. Run swagger-ui
$ npm run dev

# 5. Cleanup
$ cd /path/to/swagger-ui
$ npm unlink --no-save swagger-client
$ npm install
$ cd /path/to/swagger-js
$ npm unlink