From c2fe3f9af3e6b848a9f07089c122c515b428e818 Mon Sep 17 00:00:00 2001 From: MugeSo Date: Tue, 16 Feb 2016 16:22:58 +0900 Subject: [PATCH 1/5] Add definition for express-openapi npm: https://www.npmjs.com/package/express-openapi github: https://github.com/kogosoftwarellc/express-openapi --- express-openapi/express-openapi-tests.ts | 20 ++ express-openapi/express-openapi.d.ts | 293 +++++++++++++++++++++++ 2 files changed, 313 insertions(+) create mode 100644 express-openapi/express-openapi-tests.ts create mode 100644 express-openapi/express-openapi.d.ts diff --git a/express-openapi/express-openapi-tests.ts b/express-openapi/express-openapi-tests.ts new file mode 100644 index 000000000..ca79c90ed --- /dev/null +++ b/express-openapi/express-openapi-tests.ts @@ -0,0 +1,20 @@ +/// +/// + +import express = require('express'); +import openapi = require('express-openapi'); + +var app = express(); + +var api:openapi.InitializedApi; +api = openapi.initialize({ + apiDoc: require('./api-doc.js'), + app: app, + routes: './api-routes' +}); + +app.use(function (err, req, res, next) { + res.status(err.status).json(err); +}); + +app.listen(3000); \ No newline at end of file diff --git a/express-openapi/express-openapi.d.ts b/express-openapi/express-openapi.d.ts new file mode 100644 index 000000000..4aca41421 --- /dev/null +++ b/express-openapi/express-openapi.d.ts @@ -0,0 +1,293 @@ +// Type definitions for express-openapi 0.6.x +// Project: https://github.com/kogosoftwarellc/express-openapi +// Definitions by: TANAKA Koichi +// Definitions: https://github.com/borisyankov/DefinitelyTyped + +/* =================== USAGE =================== + import express = require('express'); + import bodyParser = require('body-parser'); + import openapi = require('express-openapi'); + import cors = require('cors'); + + var app = express(); + app.use(cors()); + app.use(bodyParser.json()); + + var api: openapi.InitializedApi; + api = openapi.initialize({ + apiDoc: require('./api-doc.js'), + app: app, + routes: './api-routes' + }); + + app.use(function(err, req, res, next) { + res.status(err.status).json(err); + }); + + app.listen(3000); + =============================================== */ + +/// + +declare module "express-openapi" { + import express = require('express'); + + export function initialize(args:Args):InitializedApi; + + export interface InitializedApi { + apiDoc: OpenApi.ApiDefinition; + } + + export module OpenApi { + export interface ApiDefinition { + swagger: string + info: InfoObject + host?: string + basePath?: string + schemes?: string[] + consumes?: MimeTypes + produces?: MimeTypes + paths: PathsObject + definitions?: DefinitionsObject + parameters?: ParametersDefinitionsObject + responses?: ResponsesDefinitionsObject + securityDefinitions?: SecurityDefinitionsObject + security?: SecurityRequirementObject[] + tags?: TagObject[] + externalDocs?: ExternalDocumentationObject + } + + type MimeTypes = string[] + + export interface InfoObject { + title: string + description?: string + termsOfService?: string + contact?: ContactObject + license?: LicenseObject + version: string + } + + export interface ContactObject { + name?: string + url?: string + email?: string + } + + export interface LicenseObject { + name: string + url?: string + } + + export interface PathsObject { + [index: string]: PathItemObject|any + } + + export interface PathItemObject { + $ref?: string + get?: OperationObject + put?: OperationObject + post?: OperationObject + 'delete'?: OperationObject + options?: OperationObject + head?: OperationObject + patch?: OperationObject + parameters?: Parameters + } + + export interface OperationObject { + tags?: string[] + summary?: string + description?: string + externalDocs?: ExternalDocumentationObject + operationId?: string + consumes?: MimeTypes + produces?: MimeTypes + parameters?: Parameters + responses: ResponsesObject + schemes?: string[] + deprecated?: boolean + security?: SecurityRequirementObject[], + [index: string]: any + } + + export interface DefinitionsObject { + [index: string]: SchemaObject + } + + export interface ResponsesObject { + [index: string]: Response|any + 'default': Response + } + + type Response = ResponseObject|ReferenceObject + + export interface ResponsesDefinitionsObject { + [index: string]: ResponseObject + } + + export interface ResponseObject { + description: string + schema?: SchemaObject + headers?: HeadersObject + examples?: ExampleObject + } + + export interface HeadersObject { + [index: string]: HeaderObject + } + + export interface HeaderObject extends ItemsObject { + } + + export interface ExampleObject { + [index: string]: any + } + + export interface SecurityDefinitionsObject { + [index: string]: SecuritySchemeObject + } + + export interface SecuritySchemeObject { + type: string + description?: string + name: string + 'in': string + flow: string + authorizationUrl: string + tokenUrl: string + scopes: ScopesObject + } + + export interface ScopesObject { + [index: string]: any + } + + export interface SecurityRequirementObject { + [index: string]: string[] + } + + export interface TagObject { + name: string + description?: string + externalDocs?: ExternalDocumentationObject + } + + export interface ItemsObject { + type: string + format?: string + items?: ItemsObject + collectionFormat?: string + 'default'?: any + maximum?: number + exclusiveMaximum: boolean + minimum?: number + exclusiveMinimum?: boolean + maxLength?: number + minLength?: number + pattern?: string + maxItems?: number + minItems?: number + uniqueItems?: boolean + 'enum'?: any[] + multipleOf?: number + } + + export interface ParametersDefinitionsObject { + [index: string]: ParameterObject + } + + type Parameters = (ParameterObject|ReferenceObject)[] + + export interface ParameterObject { + name: string + 'in': string + description?: string + required?: boolean + } + + export interface InBodyParameterObject extends ParameterObject { + schema: SchemaObject + } + + export interface GeneralParameterObject extends ParameterObject, ItemsObject { + allowEmptyValue?: boolean + } + + export interface ReferenceObject { + $ref: string + } + + export interface ExternalDocumentationObject { + [index: string]: any + description?: string + url: string + } + + export interface SchemaObject extends IJsonSchema { + [index: string]: any + discriminator?: string + readOnly?: boolean + xml?: XMLObject + externalDocs: ExternalDocumentationObject + example: any + } + + export interface XMLObject { + [index: string]: any + name?: string + namespace?: string + prefix?: string + attribute?: boolean + wrapped?: boolean + } + } + + export interface Args { + apiDoc: OpenApi.ApiDefinition, + app: express.Application, + routes: string + } + + interface IJsonSchema { + id?: string + $schema?: string + title?: string + description?: string + multipleOf?: number + maximum?: number + exclusiveMaximum?: boolean + minimum?: number + exclusiveMinimum?: boolean + maxLength?: number + minLength?: number + pattern?: string + additionalItems?: boolean | IJsonSchema + items?: IJsonSchema | IJsonSchema[] + maxItems?: number + minItems?: number + uniqueItems?: boolean + maxProperties?: number + minProperties?: number + required?: string[] + additionalProperties?: boolean | IJsonSchema + definitions?: { + [name: string]: IJsonSchema + } + properties?: { + [name: string]: IJsonSchema + } + patternProperties?: { + [name: string]: IJsonSchema + } + dependencies?: { + [name: string]: IJsonSchema | string[] + } + 'enum'?: any[] + type?: string | string[] + allOf?: IJsonSchema[] + anyOf?: IJsonSchema[] + oneOf?: IJsonSchema[] + not?: IJsonSchema + } +} From cbe236ec27da547d72a2249f69242eb3ebe07bf4 Mon Sep 17 00:00:00 2001 From: MugeSo Date: Tue, 16 Feb 2016 18:03:17 +0900 Subject: [PATCH 2/5] express-openapi: fix definition for OpenAPI definition fix exclusiveMaximuma property is now optional fix Parameters Object is now array of union type of InBodyParameter, GeneralParameter and Reference Object --- express-openapi/express-openapi.d.ts | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/express-openapi/express-openapi.d.ts b/express-openapi/express-openapi.d.ts index 4aca41421..633407ee1 100644 --- a/express-openapi/express-openapi.d.ts +++ b/express-openapi/express-openapi.d.ts @@ -180,7 +180,7 @@ declare module "express-openapi" { collectionFormat?: string 'default'?: any maximum?: number - exclusiveMaximum: boolean + exclusiveMaximum?: boolean minimum?: number exclusiveMinimum?: boolean maxLength?: number @@ -197,9 +197,11 @@ declare module "express-openapi" { [index: string]: ParameterObject } - type Parameters = (ParameterObject|ReferenceObject)[] + type Parameters = (ReferenceObject|Parameter)[] - export interface ParameterObject { + type Parameter = (InBodyParameterObject|GeneralParameterObject); + + interface ParameterObject { name: string 'in': string description?: string From 1d3b1d6a61d308fbd36f603bb316f4b5e9708d87 Mon Sep 17 00:00:00 2001 From: MugeSo Date: Tue, 16 Feb 2016 18:10:12 +0900 Subject: [PATCH 3/5] express-openapi: Add definition for path item module --- express-openapi/express-openapi-tests.ts | 43 +++++++++++++++++++++--- express-openapi/express-openapi.d.ts | 22 ++++++++++++ 2 files changed, 61 insertions(+), 4 deletions(-) diff --git a/express-openapi/express-openapi-tests.ts b/express-openapi/express-openapi-tests.ts index ca79c90ed..226f97939 100644 --- a/express-openapi/express-openapi-tests.ts +++ b/express-openapi/express-openapi-tests.ts @@ -13,8 +13,43 @@ api = openapi.initialize({ routes: './api-routes' }); -app.use(function (err, req, res, next) { - res.status(err.status).json(err); -}); +app.listen(3000); -app.listen(3000); \ No newline at end of file +// "./api-routes/user/{id}.ts" +export var get: openapi.Operation = (req, res, next) => { +}; + +export var post: openapi.Operation = [(req, res, next) => {}]; + +export var parameters = [ + { + name: 'id', + in: 'path', + type: 'string' + } +]; + +get.apiDoc = { + description: 'get user information', + operationId: 'getUser', + parameters: [ + { + name: 'includeDetail', + in: 'query', + type: 'boolean' + } + ], + responses: { + default: {$ref: '#/definitions/error'} + }, + "x-some-vendor-property": {} +}; + +post.apiDoc = { + description: 'post to user', + operationId: 'postToUser', + responses: { + default: {$ref: '#/definitions/error'} + }, + "x-some-vendor-property": {} +} \ No newline at end of file diff --git a/express-openapi/express-openapi.d.ts b/express-openapi/express-openapi.d.ts index 633407ee1..a769cc7df 100644 --- a/express-openapi/express-openapi.d.ts +++ b/express-openapi/express-openapi.d.ts @@ -251,6 +251,28 @@ declare module "express-openapi" { routes: string } + export interface OperationFunction extends express.RequestHandler { + apiDoc?: OpenApi.OperationObject; + } + + export interface OperationHandlerArray { + apiDoc?: OpenApi.OperationObject; + [index: number]: express.RequestHandler; + } + + export type Operation = OperationFunction | OperationHandlerArray; + + export interface PathModule { + parameters?: OpenApi.Parameters; + get?: Operation; + put?: Operation; + post?: Operation; + delete?: Operation; + patch?: Operation; + options?: Operation; + head?: Operation; + } + interface IJsonSchema { id?: string $schema?: string From 01d18f8a9140e6b7601219b549ac34fd8bf1f9ee Mon Sep 17 00:00:00 2001 From: MugeSo Date: Tue, 16 Feb 2016 18:14:17 +0900 Subject: [PATCH 4/5] express-openapi: Add empty line at EOF --- express-openapi/express-openapi-tests.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/express-openapi/express-openapi-tests.ts b/express-openapi/express-openapi-tests.ts index 226f97939..3ea94ffa9 100644 --- a/express-openapi/express-openapi-tests.ts +++ b/express-openapi/express-openapi-tests.ts @@ -52,4 +52,4 @@ post.apiDoc = { default: {$ref: '#/definitions/error'} }, "x-some-vendor-property": {} -} \ No newline at end of file +} From 0d0f6fe1e3279ccce48531a23062ed03ffb91899 Mon Sep 17 00:00:00 2001 From: MugeSo Date: Wed, 17 Feb 2016 10:14:29 +0900 Subject: [PATCH 5/5] express-openapi: Allow reference in schema property of response object --- express-openapi/express-openapi-tests.ts | 4 ++++ express-openapi/express-openapi.d.ts | 6 ++++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/express-openapi/express-openapi-tests.ts b/express-openapi/express-openapi-tests.ts index 3ea94ffa9..81cec3ee8 100644 --- a/express-openapi/express-openapi-tests.ts +++ b/express-openapi/express-openapi-tests.ts @@ -40,6 +40,10 @@ get.apiDoc = { } ], responses: { + 200: { + description: "valid user object", + schema: {$ref: '#/definitions/user'} + }, default: {$ref: '#/definitions/error'} }, "x-some-vendor-property": {} diff --git a/express-openapi/express-openapi.d.ts b/express-openapi/express-openapi.d.ts index a769cc7df..a28056c9f 100644 --- a/express-openapi/express-openapi.d.ts +++ b/express-openapi/express-openapi.d.ts @@ -128,7 +128,7 @@ declare module "express-openapi" { export interface ResponseObject { description: string - schema?: SchemaObject + schema?: Schema headers?: HeadersObject examples?: ExampleObject } @@ -209,7 +209,7 @@ declare module "express-openapi" { } export interface InBodyParameterObject extends ParameterObject { - schema: SchemaObject + schema: Schema } export interface GeneralParameterObject extends ParameterObject, ItemsObject { @@ -226,6 +226,8 @@ declare module "express-openapi" { url: string } + type Schema = SchemaObject | ReferenceObject + export interface SchemaObject extends IJsonSchema { [index: string]: any discriminator?: string