OpenAPI
OpenAPI представляет собой формализованную спецификацию и полноценный фреймворк для описания, создания, использования и визуализации веб-сервисов REST. Задачей является позволить клиентским системам и документации синхронизировать свои обновления с изменениями на сервере. Это достигается тем, что методы, параметры, модели и другие элементы посредством OpenAPI интегрируются с программным обеспечением сервера и всё время с ним синхронизируются
Для того чтобы сгенерировать файл OpenApi вам необходимо подготовить настройки приложения для него, к примеру:
export const settings: AppSettings = { areas: [HomeArea, InfoArea, HealthArea, RootArea], middlewares: [Log], logging: false,};
Затем внести основные настройки OpenApi c помощью AlosaurOpenApiBuilder: openapi.ts
AlosaurOpenApiBuilder.create(settings) .registerControllers() .addTitle("Basic Application") .addVersion("1.0.0") .addDescription("Example Alosaur OpenApi generate") .addServer({ url: "http://localhost:8000", description: "Local server", }) .saveToFile("./examples/basic/api.json");
Затем выполнить команду для генерации файла api.json
deno run -A --config ./src/tsconfig.lib.json examples/basic/openapi.ts
#
Type referenceFor support type references you can use JSDoc with Deno doc parse like this:
// Parse controllers. Input path to your applicationconst docs = await AlosaurOpenApiBuilder.parseDenoDoc("./openapi/e2e/app.ts");
// create builder and add docs, then register controllers and add scheme componentsconst builder = AlosaurOpenApiBuilder.create(settings) .addDenoDocs(docs) .registerControllers() .addSchemeComponents()
How to teaching how to correctly assemble controllers?
Example:
/** * Product controller * @decorator Controller */@Controller()export class ProductController { /** * Gets product by id * @summary action test * @remarks Awesomeness! * @param {id} The product id * @decorator Get */ @Get("/:id") GetById(@Param("id") id: string) { return new Product(); }}
You can also add what media types can be expected in the body. Use RequestBody param in JsDoc
/** * Create product * @param product * @RequestBody application/xml * @RequestBody application/json */ @Post("/") @ActionParam(0, Body()) Create(product: Product) { }
You can also add what types can be returned from a controller method. Use decorator ProducesResponse
/** * Gets product by id * @summary action test * @remarks Awesomeness! * @param {id} The product id */@Get("/:id")@ProducesResponse({ code: 200, type: Product, description: "Product found" })@ProducesResponse({ code: 404, type: NotFoundResult, description: "Product has missing/invalid values" })@ProducesResponse({ code: 500, description: "Oops! Can't create your product right now" })@ActionParam(0, Param("id"))GetById(id: string) { return new Product();}
To declare more information in types and models you can add other JsDoc parameters
/** * Entity of product */export class Product { /** * @summary Identifer of code * @example 1 */ id?: number;
/** * @summary Array of test case * @example [1,2,3] */ arr?: number[];
/** * @summary Type of product * @example {id:1} */ type?: ProductType;
/** * @maximum 100 */ count?: number;}
Alosaur openapi parser currently supports the following types and expressions:
interface PropertyJsDocObject { title?: string; pattern?: string; multipleOf?: number; maximum?: number; minimum?: number; exclusiveMaximum?: boolean; exclusiveMinimum?: boolean; maxLength?: number; minLength?: number; maxItems?: number; minItems?: number; uniqueItems?: boolean; maxProperties?: number; minProperties?: number; required?: boolean;}
Keywords:
export interface JsDocObject { example?: string; decorator?: string; default?: string; description?: string; deprecated?: boolean; required?: boolean; remarks?: string; summary?: string; format?: string; params?: string[];
/** * Request body media type uses in controllers * application/json, application/xml, text/plain, etc * https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#requestBodyObject */ RequestBody?: string[];}
Ts types, Object Date Symbol Map JSON RegExp String ArrayBuffer DataView Int8Array Uint8Array Uint8ClampedArray Int16Array Uint16Array Int32Array Uint32Array Float32Array Float64Array