Important:Before running this generator, you must create an application using the application generator.Then you must run the command from the root directory of the application.

Synopsis

Generates artifacts from an OpenAPI spec into a LoopBack application.

  1. lb4 openapi [<url>] [options]

Options

  • —url: URL or file path of the OpenAPI spec.
  • —validate: Validate the OpenAPI spec. Default: false.
  • —promote-anonymous-schemas: Promote anonymous schemas as models classes.Default: false.

Arguments

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

Supported OpenAPI spec versions

Interactive Prompts

The tool will prompt you for:

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

Generated artifacts

The command generates the following artifacts:

  • For each schema under components.schemas, a model class or typedeclaration is generated as src/models/<model-or-type-name>.model.ts.Simple types, array types, composite types (allOf/anyOf/oneOf) are mapped toTypeScript type declarations. Object types are mapped to TypeScript classes.

For example,

src/models/message.model.ts

  1. export type Message = string;

src/models/order-enum.model.ts

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

src/models/comments.model.ts

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

src/models/cart.model.ts

  1. import {model, property} from '@loopback/repository';
  2. import {CartShippingZone} from './cart-shipping-zone.model';
  3. import {CartStoreInfo} from './cart-store-info.model';
  4. import {CartWarehouse} from './cart-warehouse.model';
  6. /**
  7.  * The model class is generated from OpenAPI schema - Cart
  8.  * Cart
  9.  */
  10. @model({name: 'Cart'})
  11. export class Cart {
  12.   constructor(data?: Partial<Cart>) {
  13.     if (data != null && typeof data === 'object') {
  14.       Object.assign(this, data);
  15.     }
  16.   }
  18.   @property({name: 'additional_fields'})
  19.   additional_fields?: {};
  21.   @property({name: 'custom_fields'})
  22.   custom_fields?: {};
  24.   @property({name: 'db_prefix'})
  25.   db_prefix?: string;
  27.   @property({name: 'name'})
  28.   name?: string;
  30.   @property({name: 'shipping_zones'})
  31.   shipping_zones?: CartShippingZone[];
  33.   @property({name: 'stores_info'})
  34.   stores_info?: CartStoreInfo[];
  36.   @property({name: 'url'})
  37.   url?: string;
  39.   @property({name: 'version'})
  40.   version?: string;
  42.   @property({name: 'warehouses'})
  43.   warehouses?: CartWarehouse[];
  44. }

src/models/id-type.model.ts

  1. export type IdType = string | number;

src/models/pet.model.ts

  1. import {NewPet} from './new-pet.model.ts';
  2. export type Pet = NewPet & {id: number};
  • Anonymous schemas of object/array types are generated as inline TypeScripttype literals or separate model classes/types depending on—promote-anonymous-schemas flag (default to false).For example, the following OpenAPI spec snippet uses anonymous schemas forrequest and response body objects.
  1. openapi: 3.0.0
  2. // ...
  3. paths:
  4.   // ...
  5.   /{dataset}/{version}/records:
  6.     post:
  7.       // ...
  8.       operationId: perform-search
  9.       parameters:
  10.         // ...
  11.       responses:
  12.         '200':
  13.           description: successful operation
  14.           content:
  15.             application/json:
  16.               schema:
  17.                 type: array
  18.                 items:
  19.                   type: object
  20.                   additionalProperties:
  21.                     type: object
  22.         '404':
  23.           description: No matching record found for the given criteria.
  24.       requestBody:
  25.         content:
  26.           application/x-www-form-urlencoded:
  27.             schema:
  28.               type: object
  29.               properties:
  30.                 criteria:
  31.                   description: >-
  32.                     Uses Lucene Query Syntax in the format of
  33.                     propertyName:value, propertyName:[num1 TO num2] and date
  34.                     range format: propertyName:[yyyyMMdd TO yyyyMMdd]. In the
  35.                     response please see the 'docs' element which has the list of
  36.                     record objects. Each record structure would consist of all
  37.                     the fields and their corresponding values.
  38.                   type: string
  39.                   default: '*:*'
  40.                 start:
  41.                   description: Starting record number. Default value is 0.
  42.                   type: integer
  43.                   default: 0
  44.                 rows:
  45.                   description: >-
  46.                     Specify number of rows to be returned. If you run the search
  47.                     with default values, in the response you will see 'numFound'
  48.                     attribute which will tell the number of records available in
  49.                     the dataset.
  50.                   type: integer
  51.                   default: 100
  52.               required:
  53.                 - criteria

Without —promote-anonymous-schemas, no separate files are generated foranonymous schemas. The controller class uses inline TypeScript type literals asshown below.

src/controllers/search.controller.ts

  1. @operation('post', '/{dataset}/{version}/records')
  2.   async performSearch(
  3.     @requestBody()
  4.     body: {
  5.       criteria: string;
  6.       start?: number;
  7.       rows?: number;
  8.     },
  9.     @param({name: 'version', in: 'path'}) version: string,
  10.     @param({name: 'dataset', in: 'path'}) dataset: string,
  11.   ): Promise<
  12.     {
  13.       [additionalProperty: string]: {};
  14.     }[]
  15.   > {
  16.     throw new Error('Not implemented');
  17.   }

On contrast, if lb4 openapi —promote-anonymous-schemas is used, twoadditional model files are generated:

src/models/perform-search-body.model.ts

  1. /* eslint-disable @typescript-eslint/no-explicit-any */
  2. import {model, property} from '@loopback/repository';
  4. /**
  5.  * The model class is generated from OpenAPI schema - performSearchBody
  6.  * performSearchBody
  7.  */
  8. @model({name: 'performSearchBody'})
  9. export class PerformSearchBody {
  10.   constructor(data?: Partial<PerformSearchBody>) {
  11.     if (data != null && typeof data === 'object') {
  12.       Object.assign(this, data);
  13.     }
  14.   }
  16.   /**
  17.    * Uses Lucene Query Syntax in the format of propertyName:value, propertyName:[num1 TO num2] and date range format: propertyName:[yyyyMMdd TO yyyyMMdd]. In the response please see the 'docs' element which has the list of record objects. Each record structure would consist of all the fields and their corresponding values.
  18.    */
  19.   @property({name: 'criteria'})
  20.   criteria: string = '*:*';
  22.   /**
  23.    * Starting record number. Default value is 0.
  24.    */
  25.   @property({name: 'start'})
  26.   start?: number = 0;
  28.   /**
  29.    * Specify number of rows to be returned. If you run the search with default values, in the response you will see 'numFound' attribute which will tell the number of records available in the dataset.
  30.    */
  31.   @property({name: 'rows'})
  32.   rows?: number = 100;
  33. }

src/models/perform-search-response-body.model.ts

  1. export type PerformSearchResponseBody = {
  2.   [additionalProperty: string]: {};
  3. }[];
  • The generator groups operations (paths.<path>.<verb>) by tags. If no tag ispresent, it defaults to OpenApi. For each tag, a controller class isgenerated as src/controllers/<tag-name>.controller.ts to hold alloperations with the same tag.Controller class names are derived from tag names. The x-controller-nameproperty of an operation can be used to customize the controller name. Methodnames are derived from operationIds. They can be configured usingx-operation-name.

For example,

  1. import {operation, param} from '@loopback/rest';
  2. import {DateTime} from '../models/date-time.model';
  4. /**
  5.  * The controller class is generated from OpenAPI spec with operations tagged
  6.  * by account
  7.  *
  8.  */
  9. export class AccountController {
  10.   constructor() {}
  12.   /**
  13.    * Get list of carts.
  14.    */
  15.   @operation('get', '/account.cart.list.json')
  16.   async accountCartList(
  17.     @param({name: 'params', in: 'query'}) params: string,
  18.     @param({name: 'exclude', in: 'query'}) exclude: string,
  19.     @param({name: 'request_from_date', in: 'query'}) request_from_date: string,
  20.     @param({name: 'request_to_date', in: 'query'}) request_to_date: string,
  21.   ): Promise<{
  22.     result?: {
  23.       carts?: {
  24.         cart_id?: string;
  25.         id?: string;
  26.         store_key?: string;
  27.         total_calls?: string;
  28.         url?: string;
  29.       }[];
  30.       carts_count?: number;
  31.     };
  32.     return_code?: number;
  33.     return_message?: string;
  34.   }> {
  35.     throw new Error('Not implemented');
  36.   }
  38.   /**
  39.    * Update configs in the API2Cart database.
  40.    */
  41.   @operation('put', '/account.config.update.json')
  42.   async accountConfigUpdate(
  43.     @param({name: 'db_tables_prefix', in: 'query'}) db_tables_prefix: string,
  44.     @param({name: 'client_id', in: 'query'}) client_id: string,
  45.     @param({name: 'bridge_url', in: 'query'}) bridge_url: string,
  46.     @param({name: 'store_root', in: 'query'}) store_root: string,
  47.     @param({name: 'shared_secret', in: 'query'}) shared_secret: string,
  48.   ): Promise<{
  49.     result?: {
  50.       updated_items?: number;
  51.     };
  52.     return_code?: number;
  53.     return_message?: string;
  54.   }> {
  55.     throw new Error('Not implemented');
  56.   }
  58.   /**
  59.    * List webhooks that was not delivered to the callback.
  60.    */
  61.   @operation('get', '/account.failed_webhooks.json')
  62.   async accountFailedWebhooks(
  63.     @param({name: 'count', in: 'query'}) count: number,
  64.     @param({name: 'start', in: 'query'}) start: number,
  65.     @param({name: 'ids', in: 'query'}) ids: string,
  66.   ): Promise<{
  67.     result?: {
  68.       all_failed_webhook?: string;
  69.       webhook?: {
  70.         entity_id?: string;
  71.         time?: DateTime;
  72.         webhook_id?: number;
  73.       }[];
  74.     };
  75.     return_code?: number;
  76.     return_message?: string;
  77.   }> {
  78.     throw new Error('Not implemented');
  79.   }
  80. }

OpenAPI Examples

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