Page Contents

Synopsis

Generates artifacts from an OpenAPI spec into a LoopBack application.

lb4 openapi [<url>] [options]

Options

  • --url: URL or file path of the OpenAPI spec.
  • --validate: Validate the OpenAPI spec. Default: false.

Arguments

<url>: URL or file path of the OpenAPI spec. Type: String. Required: false.

Supported OpenAPI spec versions

Please note Swagger 2.0 specs are converted to OpenAPI 3.0 internally using swagger2openapi.

Interactive Prompts

The tool will prompt you for:

  • URL or file path of the OpenAPI spec If the url or file path is supplied from the command line, the prompt is skipped.
  • Select controllers to be generated You can select what controllers will be generated based on OpenAPI tags.

Generated artifacts

The command generates the following artifacts:

  1. For each schema under components.schemas, a model class or type declaration is generated as src/models/<model-or-type-name>.model.ts.

Simple types, array types, composite types (allOf/anyOf/oneOf) are mapped to TypeScript type declarations. Object types are mapped to TypeScript classes.

For example,

src/models/message.model.ts:

export type Message = string;

src/models/order-enum.model.ts:

export type OrderEnum = 'ascending' | 'descending';

src/models/comments.model.ts:

import {Comment} from './comment.model';
export type Comments = Comment[];

src/models/cart.model.ts:

import {model, property} from '@loopback/repository';
import {CartShippingZone} from './cart-shipping-zone.model';
import {CartStoreInfo} from './cart-store-info.model';
import {CartWarehouse} from './cart-warehouse.model';

/**
 * The model class is generated from OpenAPI schema - Cart
 * Cart
 */
@model({name: 'Cart'})
export class Cart {
  constructor(data?: Partial<Cart>) {
    if (data != null && typeof data === 'object') {
      Object.assign(this, data);
    }
  }

  @property({name: 'additional_fields'})
  additional_fields?: {};

  @property({name: 'custom_fields'})
  custom_fields?: {};

  @property({name: 'db_prefix'})
  db_prefix?: string;

  @property({name: 'name'})
  name?: string;

  @property({name: 'shipping_zones'})
  shipping_zones?: CartShippingZone[];

  @property({name: 'stores_info'})
  stores_info?: CartStoreInfo[];

  @property({name: 'url'})
  url?: string;

  @property({name: 'version'})
  version?: string;

  @property({name: 'warehouses'})
  warehouses?: CartWarehouse[];
}

src/models/id-type.model.ts:

export type IdType = string | number;

src/models/pet.model.ts:

import {NewPet} from './new-pet.model.ts';
export type Pet = NewPet & {id: number};
  1. The generator groups operations (paths.<path>.<verb>) by tags. If no tag is present, it defaults to OpenApi. For each tag, a controller class is generated as src/controllers/<tag-name>.controller.ts to hold all operations with the same tag.

Controller class names are derived from tag names. The x-controller-name property of an operation can be used to customize the controller name. Method names are derived from operationIds. They can be configured using x-operation-name.

For example,

import {operation, param} from '@loopback/rest';
import {DateTime} from '../models/date-time.model';

/**
 * The controller class is generated from OpenAPI spec with operations tagged
 * by account
 *
 */
export class AccountController {
  constructor() {}

  /**
   * Get list of carts.
   */
  @operation('get', '/account.cart.list.json')
  async accountCartList(
    @param({name: 'params', in: 'query'}) params: string,
    @param({name: 'exclude', in: 'query'}) exclude: string,
    @param({name: 'request_from_date', in: 'query'}) request_from_date: string,
    @param({name: 'request_to_date', in: 'query'}) request_to_date: string,
  ): Promise<{
    result?: {
      carts?: {
        cart_id?: string;
        id?: string;
        store_key?: string;
        total_calls?: string;
        url?: string;
      }[];
      carts_count?: number;
    };
    return_code?: number;
    return_message?: string;
  }> {
    throw new Error('Not implemented');
  }

  /**
   * Update configs in the API2Cart database.
   */
  @operation('put', '/account.config.update.json')
  async accountConfigUpdate(
    @param({name: 'db_tables_prefix', in: 'query'}) db_tables_prefix: string,
    @param({name: 'client_id', in: 'query'}) client_id: string,
    @param({name: 'bridge_url', in: 'query'}) bridge_url: string,
    @param({name: 'store_root', in: 'query'}) store_root: string,
    @param({name: 'shared_secret', in: 'query'}) shared_secret: string,
  ): Promise<{
    result?: {
      updated_items?: number;
    };
    return_code?: number;
    return_message?: string;
  }> {
    throw new Error('Not implemented');
  }

  /**
   * List webhooks that was not delivered to the callback.
   */
  @operation('get', '/account.failed_webhooks.json')
  async accountFailedWebhooks(
    @param({name: 'count', in: 'query'}) count: number,
    @param({name: 'start', in: 'query'}) start: number,
    @param({name: 'ids', in: 'query'}) ids: string,
  ): Promise<{
    result?: {
      all_failed_webhook?: string;
      webhook?: {
        entity_id?: string;
        time?: DateTime;
        webhook_id?: number;
      }[];
    };
    return_code?: number;
    return_message?: string;
  }> {
    throw new Error('Not implemented');
  }
}

OpenAPI Examples

Try out the following specs or your own with lb4 openapi:

  • https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml
  • https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/uspto.yaml
  • https://api.apis.guru/v2/specs/api2cart.com/1.0.0/swagger.json
  • https://api.apis.guru/v2/specs/amazonaws.com/codecommit/2015-04-13/swagger.json

For more real world OpenAPI specs, see https://api.apis.guru/v2/list.json.