@midwayjs/swagger 1.2.0 → 3.0.0-beta.12

package/dist/documentBuilder.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentBuilder = void 0;
+class DocumentBuilder {
+    constructor() {
+        this.document = {
+            openapi: '3.0.1',
+            info: {
+                title: '',
+                description: '',
+                version: '1.0.0',
+                contact: {},
+            },
+            tags: [],
+            servers: [],
+            components: {},
+            paths: {},
+        };
+    }
+    setTitle(title) {
+        this.document.info.title = title;
+        return this;
+    }
+    setDescription(description) {
+        this.document.info.description = description;
+        return this;
+    }
+    setVersion(version) {
+        this.document.info.version = version;
+        return this;
+    }
+    setTermsOfService(termsOfService) {
+        this.document.info.termsOfService = termsOfService;
+        return this;
+    }
+    setContact(name, url, email) {
+        this.document.info.contact = { name, url, email };
+        return this;
+    }
+    setLicense(name, url) {
+        this.document.info.license = { name, url };
+        return this;
+    }
+    addServer(url, description, variables) {
+        this.document.servers.push({ url, description, variables });
+        return this;
+    }
+    setExternalDoc(description, url) {
+        this.document.externalDocs = { description, url };
+        return this;
+    }
+    setBasePath(path) {
+        if (this.document.basePath) {
+            if (Array.isArray(this.document.basePath)) {
+                this.document.basePath.push(path);
+            }
+            else {
+                this.document.basePath = [
+                    this.document.basePath,
+                    path,
+                ];
+            }
+        }
+        else {
+            this.document.basePath = path;
+        }
+        return this;
+    }
+    addPaths(paths) {
+        Object.assign(this.document.paths, paths);
+        return this;
+    }
+    addSchema(schema) {
+        if (!this.document.components.schemas) {
+            this.document.components.schemas = {};
+        }
+        Object.assign(this.document.components.schemas, schema);
+        return this;
+    }
+    addTag(name, description = '', externalDocs) {
+        if (Array.isArray(name)) {
+            const arr = name;
+            for (const s of arr) {
+                this.document.tags.push({
+                    name: s,
+                    description: '',
+                });
+            }
+            return this;
+        }
+        this.document.tags.push({
+            name,
+            description,
+            externalDocs,
+        });
+        return this;
+    }
+    addSecurity(name, options) {
+        this.document.components.securitySchemes = {
+            ...(this.document.components.securitySchemes || {}),
+            [name]: options,
+        };
+        return this;
+    }
+    addSecurityRequirements(name, requirements = []) {
+        let securityRequirement;
+        if (typeof name === 'string') {
+            securityRequirement = { [name]: requirements };
+        }
+        else {
+            securityRequirement = name;
+        }
+        this.document.security = (this.document.security || []).concat({
+            ...securityRequirement,
+        });
+        return this;
+    }
+    addBearerAuth(options = {
+        type: 'http',
+    }, name = 'bearer') {
+        this.addSecurity(name, {
+            type: 'http',
+            scheme: 'bearer',
+            bearerFormat: 'JWT',
+            ...options,
+        });
+        return this;
+    }
+    addOAuth2(options = {
+        type: 'oauth2',
+    }, name = 'oauth2') {
+        if (!name) {
+            name = 'oauth2';
+        }
+        this.addSecurity(name, {
+            type: 'oauth2',
+            flows: {
+                ...options === null || options === void 0 ? void 0 : options.flows,
+            },
+        });
+        return this;
+    }
+    addApiKey(options = {
+        type: 'apiKey',
+    }, name = 'api_key') {
+        if (!name) {
+            name = 'api_key';
+        }
+        this.addSecurity(name, {
+            type: 'apiKey',
+            in: 'header',
+            name,
+            ...options,
+        });
+        return this;
+    }
+    addBasicAuth(options = {
+        type: 'http',
+    }, name = 'basic') {
+        if (!name) {
+            name = 'basic';
+        }
+        this.addSecurity(name, {
+            type: 'http',
+            scheme: 'basic',
+            ...options,
+        });
+        return this;
+    }
+    addCookieAuth(cookieName = 'connect.sid', options = {
+        type: 'apiKey',
+    }, securityName = 'cookie') {
+        if (!cookieName) {
+            cookieName = 'connect.sid';
+        }
+        if (!securityName) {
+            securityName = 'cookie';
+        }
+        this.addSecurity(securityName, {
+            type: 'apiKey',
+            in: 'cookie',
+            name: cookieName,
+            ...options,
+        });
+        return this;
+    }
+    build() {
+        return this.document;
+    }
+}
+exports.DocumentBuilder = DocumentBuilder;
+//# sourceMappingURL=documentBuilder.js.map

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { AutoConfiguration as Configuration } from './configuration';
-export * from './controller/swagger';
-export * from './lib/createAPI';
-export * from './service/generator';
-export * from './interface';
+export * from './decorators';
+export * from './interfaces';
+export { SwaggerConfiguration as Configuration } from './configuration';
+export { SwaggerExplorer } from './swaggerExplorer';
+export { SwaggerMiddleware } from './swaggerMiddleware';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -10,11 +10,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Configuration = void 0;
+exports.SwaggerMiddleware = exports.SwaggerExplorer = exports.Configuration = void 0;
+__exportStar(require("./decorators"), exports);
+__exportStar(require("./interfaces"), exports);
 var configuration_1 = require("./configuration");
-Object.defineProperty(exports, "Configuration", { enumerable: true, get: function () { return configuration_1.AutoConfiguration; } });
-__exportStar(require("./controller/swagger"), exports);
-__exportStar(require("./lib/createAPI"), exports);
-__exportStar(require("./service/generator"), exports);
-__exportStar(require("./interface"), exports);
+Object.defineProperty(exports, "Configuration", { enumerable: true, get: function () { return configuration_1.SwaggerConfiguration; } });
+var swaggerExplorer_1 = require("./swaggerExplorer");
+Object.defineProperty(exports, "SwaggerExplorer", { enumerable: true, get: function () { return swaggerExplorer_1.SwaggerExplorer; } });
+var swaggerMiddleware_1 = require("./swaggerMiddleware");
+Object.defineProperty(exports, "SwaggerMiddleware", { enumerable: true, get: function () { return swaggerMiddleware_1.SwaggerMiddleware; } });
 //# sourceMappingURL=index.js.map

package/dist/interfaces/index.d.ts

@@ -0,0 +1,339 @@
+/**
+ * inspired by https://github.com/metadevpro/openapi3-ts
+ * @see https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc0/versions/3.0.md
+ */
+export interface OpenAPIObject {
+    openapi: string;
+    info: InfoObject;
+    servers?: ServerObject[];
+    paths: PathsObject;
+    components?: ComponentsObject;
+    security?: SecurityRequirementObject[];
+    tags?: TagObject[];
+    externalDocs?: ExternalDocumentationObject;
+}
+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 ServerObject {
+    url: string;
+    description?: string;
+    variables?: Record<string, ServerVariableObject>;
+}
+export interface ServerVariableObject {
+    enum?: string[] | boolean[] | number[];
+    default: string | boolean | number;
+    description?: string;
+}
+export interface ComponentsObject {
+    schemas?: Record<string, SchemaObject | ReferenceObject>;
+    responses?: Record<string, ResponseObject | ReferenceObject>;
+    parameters?: Record<string, ParameterObject | ReferenceObject>;
+    examples?: Record<string, ExampleObject | ReferenceObject>;
+    requestBodies?: Record<string, RequestBodyObject | ReferenceObject>;
+    headers?: Record<string, HeaderObject | ReferenceObject>;
+    securitySchemes?: Record<string, SecuritySchemeObject | ReferenceObject>;
+    links?: Record<string, LinkObject | ReferenceObject>;
+    callbacks?: Record<string, CallbackObject | ReferenceObject>;
+}
+export declare type PathsObject = Record<string, PathItemObject>;
+export interface PathItemObject {
+    $ref?: string;
+    summary?: string;
+    description?: string;
+    get?: OperationObject;
+    put?: OperationObject;
+    post?: OperationObject;
+    delete?: OperationObject;
+    options?: OperationObject;
+    head?: OperationObject;
+    patch?: OperationObject;
+    trace?: OperationObject;
+    servers?: ServerObject[];
+    parameters?: (ParameterObject | ReferenceObject)[];
+}
+export interface OperationObject {
+    tags?: string[];
+    summary?: string;
+    description?: string;
+    externalDocs?: ExternalDocumentationObject;
+    operationId?: string;
+    parameters?: (ParameterObject | ReferenceObject)[];
+    requestBody?: RequestBodyObject | ReferenceObject;
+    responses: ResponsesObject;
+    callbacks?: CallbacksObject;
+    deprecated?: boolean;
+    security?: SecurityRequirementObject[];
+    servers?: ServerObject[];
+}
+export interface ExternalDocumentationObject {
+    description?: string;
+    url: string;
+}
+export declare type ParameterLocation = 'query' | 'header' | 'path' | 'cookie';
+export declare type ParameterStyle = 'matrix' | 'label' | 'form' | 'simple' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject';
+export interface BaseParameterObject {
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    allowEmptyValue?: boolean;
+    style?: ParameterStyle;
+    explode?: boolean;
+    allowReserved?: boolean;
+    schema?: SchemaObject | ReferenceObject;
+    examples?: Record<string, ExampleObject | ReferenceObject>;
+    example?: any;
+    content?: ContentObject;
+}
+export interface ParameterObject extends BaseParameterObject {
+    name: string;
+    in: ParameterLocation;
+}
+export interface RequestBodyObject {
+    description?: string;
+    content: ContentObject;
+    required?: boolean;
+}
+export declare type ContentObject = Record<string, MediaTypeObject>;
+export interface MediaTypeObject {
+    schema?: SchemaObject | ReferenceObject;
+    examples?: ExamplesObject;
+    example?: any;
+    encoding?: EncodingObject;
+}
+export declare type EncodingObject = Record<string, EncodingPropertyObject>;
+export interface EncodingPropertyObject {
+    contentType?: string;
+    headers?: Record<string, HeaderObject | ReferenceObject>;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+}
+export interface ResponsesObject extends Record<string, ResponseObject | ReferenceObject | undefined> {
+    default?: ResponseObject | ReferenceObject;
+}
+export interface ResponseObject {
+    description: string;
+    headers?: HeadersObject;
+    content?: ContentObject;
+    links?: LinksObject;
+}
+export declare type CallbacksObject = Record<string, CallbackObject | ReferenceObject>;
+export declare type CallbackObject = Record<string, PathItemObject>;
+export declare type HeadersObject = Record<string, HeaderObject | ReferenceObject>;
+export interface ExampleObject {
+    summary?: string;
+    description?: string;
+    value?: any;
+    externalValue?: string;
+}
+export declare type LinksObject = Record<string, LinkObject | ReferenceObject>;
+export interface LinkObject {
+    operationRef?: string;
+    operationId?: string;
+    parameters?: LinkParametersObject;
+    requestBody?: any | string;
+    description?: string;
+    server?: ServerObject;
+}
+export declare type LinkParametersObject = Record<string, any>;
+export declare type HeaderObject = BaseParameterObject;
+export interface TagObject {
+    name: string;
+    description?: string;
+    externalDocs?: ExternalDocumentationObject;
+}
+export declare type ExamplesObject = Record<string, ExampleObject | ReferenceObject>;
+export interface ReferenceObject {
+    $ref: string;
+}
+export interface SchemaObject {
+    nullable?: boolean;
+    discriminator?: DiscriminatorObject;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    xml?: XmlObject;
+    externalDocs?: ExternalDocumentationObject;
+    example?: any;
+    examples?: any[] | Record<string, any>;
+    deprecated?: boolean;
+    type?: string;
+    allOf?: (SchemaObject | ReferenceObject)[];
+    oneOf?: (SchemaObject | ReferenceObject)[];
+    anyOf?: (SchemaObject | ReferenceObject)[];
+    not?: SchemaObject | ReferenceObject;
+    items?: SchemaObject | ReferenceObject;
+    properties?: Record<string, SchemaObject | ReferenceObject>;
+    additionalProperties?: SchemaObject | ReferenceObject | boolean;
+    patternProperties?: SchemaObject | ReferenceObject | any;
+    description?: string;
+    format?: string;
+    default?: any;
+    title?: string;
+    multipleOf?: number;
+    maximum?: number;
+    exclusiveMaximum?: boolean;
+    minimum?: number;
+    exclusiveMinimum?: boolean;
+    maxLength?: number;
+    minLength?: number;
+    pattern?: string;
+    maxItems?: number;
+    minItems?: number;
+    uniqueItems?: boolean;
+    maxProperties?: number;
+    minProperties?: number;
+    required?: string[];
+    enum?: any[];
+}
+export declare type SchemasObject = Record<string, SchemaObject>;
+export interface DiscriminatorObject {
+    propertyName: string;
+    mapping?: Record<string, string>;
+}
+export interface XmlObject {
+    name?: string;
+    namespace?: string;
+    prefix?: string;
+    attribute?: boolean;
+    wrapped?: boolean;
+}
+export declare type SecuritySchemeType = 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
+export interface SecuritySchemeObject {
+    type: SecuritySchemeType;
+    description?: string;
+    name?: string;
+    in?: string;
+    scheme?: string;
+    bearerFormat?: string;
+    flows?: OAuthFlowsObject;
+    openIdConnectUrl?: string;
+}
+export interface OAuthFlowsObject {
+    implicit?: OAuthFlowObject;
+    password?: OAuthFlowObject;
+    clientCredentials?: OAuthFlowObject;
+    authorizationCode?: OAuthFlowObject;
+}
+export interface OAuthFlowObject {
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    refreshUrl?: string;
+    scopes: ScopesObject;
+}
+export declare type ScopesObject = Record<string, any>;
+export declare type SecurityRequirementObject = Record<string, string[]>;
+/**
+ * 非 open api spec
+ */
+export declare type SwaggerEnumType = string[] | number[] | (string | number)[] | Record<number, string>;
+export interface Type<T = any> extends Function {
+    new (...args: any[]): T;
+}
+export interface SchemaObjectMetadata extends Omit<SchemaObject, 'type' | 'required'> {
+    type?: Type<unknown> | [Type] | string | Record<string, any>;
+    isArray?: boolean;
+    required?: boolean;
+    name?: string;
+    enumName?: string;
+}
+export declare type AuthType = 'basic' | 'bearer' | 'cookie' | 'oauth2' | 'apikey' | 'custom';
+/**
+ * 继承自 https://swagger.io/specification/#security-scheme-object
+ */
+export interface AuthOptions extends Omit<SecuritySchemeObject, 'type'> {
+    /**
+     * 验权类型
+     * basic  => http basic 验证
+     * bearer => http jwt 验证
+     * cookie => cookie 方式验证
+     * oauth2 => 使用 oauth2
+     * apikey => apiKey
+     * custom => 自定义方式
+     */
+    authType: AuthType;
+    /**
+     * https://swagger.io/specification/#security-scheme-object type 字段
+     */
+    type?: SecuritySchemeType;
+    /**
+     * authType = cookie 时可以修改，通过 ApiCookie 装饰器关联的名称
+     */
+    securityName?: string;
+    /**
+     * authType = cookie 时可以修改，cookie 的名称
+     */
+    cookieName?: string;
+}
+/**
+ * see https://swagger.io/specification/
+ */
+export interface SwaggerOptions {
+    /**
+     * 默认值: My Project
+     * https://swagger.io/specification/#info-object title 字段
+     */
+    title?: string;
+    /**
+     * 默认值: This is a swagger-ui for midwayjs project
+     * https://swagger.io/specification/#info-object description 字段
+     */
+    description?: string;
+    /**
+     * 默认值: 1.0.0
+     * https://swagger.io/specification/#info-object version 字段
+     */
+    version?: string;
+    /**
+     * https://swagger.io/specification/#info-object contact 字段
+     */
+    contact?: ContactObject;
+    /**
+     * https://swagger.io/specification/#info-object license 字段
+     */
+    license?: LicenseObject;
+    /**
+     * https://swagger.io/specification/#info-object termsOfService 字段
+     */
+    termsOfService?: string;
+    /**
+     * https://swagger.io/specification/#openapi-object externalDocs 字段
+     */
+    externalDocs?: ExternalDocumentationObject;
+    /**
+     * https://swagger.io/specification/#openapi-object servers 字段
+     */
+    servers?: Array<ServerObject>;
+    /**
+     * https://swagger.io/specification/#openapi-object tags 字段
+     */
+    tags?: Array<TagObject>;
+    /**
+     * 可以参考 https://swagger.io/specification/#security-scheme-object
+     */
+    auth?: AuthOptions | AuthOptions[];
+    /**
+     * api 的 根路径
+     */
+    basePath?: string | string[];
+    /**
+     * 默认值: /swagger-ui
+     * 访问 swagger ui 的路径
+     */
+    swaggerPath?: string;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/interfaces/index.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * inspired by https://github.com/metadevpro/openapi3-ts
+ * @see https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc0/versions/3.0.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/swaggerExplorer.d.ts

@@ -0,0 +1,30 @@
+export declare class SwaggerExplorer {
+    private swaggerConfig;
+    private documentBuilder;
+    init(): Promise<void>;
+    scanApp(): void;
+    getData(): Omit<import("./interfaces").OpenAPIObject, "paths">;
+    private generatePath;
+    /**
+     * 构造 router 提取方法
+     */
+    private generateRouteMethod;
+    /**
+     * 提取参数
+     * @param params
+     * @param p
+     */
+    private parseFromParamsToP;
+    /**
+     * 解析类型的 ApiProperty
+     * @param clzz
+     */
+    private parseClzz;
+    /**
+     * 授权验证
+     * @param opts
+     * @returns
+     */
+    private setAuth;
+}
+//# sourceMappingURL=swaggerExplorer.d.ts.map