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:
- For each schema under
components.schemas
, a model class or type declaration is generated assrc/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};
- The generator groups operations (
paths.<path>.<verb>
) by tags. If no tag is present, it defaults toOpenApi
. For each tag, a controller class is generated assrc/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 operationId
s. 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.