@spinajs/http-swagger 2.0.470 → 2.0.472

package/lib/cjs/openapi-builder.d.ts

@@ -0,0 +1,153 @@
+import { ClassInfo } from '@spinajs/di';
+import { BaseController } from '@spinajs/http';
+import { IOpenApiDocument, ISwaggerCacheEntry, ISwaggerConfig } from './interfaces.js';
+export declare class OpenApiBuilder {
+    private config;
+    private document;
+    private tags;
+    private registeredResponses;
+    private errorSchemaRegistered;
+    private registeredPolicies;
+    private policySectionEntries;
+    private infoDescriptionBase;
+    constructor(config: ISwaggerConfig);
+    /**
+     * Add a controller's routes to the OpenAPI document.
+     */
+    addController(controller: ClassInfo<BaseController>, docCache: ISwaggerCacheEntry): void;
+    /**
+     * Surface policy information on an operation:
+     *   - merge controller-level and route-level policies (controller policies run first)
+     *   - vendor extension `x-policies` for tooling
+     *   - human-readable line appended to `description`; each policy links to the
+     *     reusable "Policies" section appended to `info.description`
+     *
+     * The JSDoc descriptions for each unique policy are registered once on the
+     * document via `registerPolicyReference()`.
+     */
+    private applyPolicies;
+    /**
+     * Lazily register a policy in the document-level "Policies" section.
+     * OpenAPI 3.0 has no first-class "policies" components bucket, so we render
+     * them into `info.description` as a markdown anchor that Swagger UI can
+     * link to from operation descriptions.
+     */
+    private registerPolicyReference;
+    private policyAnchor;
+    private firstSentence;
+    /**
+     * Read rbac-http's controller descriptor via the global metadata symbol.
+     * Returns undefined when the controller isn't RBAC-decorated.
+     */
+    private readRbacDescriptor;
+    /**
+     * Attach RBAC info to an operation:
+     *   - vendor extensions `x-rbac-resource` and `x-rbac-permissions` for
+     *     tooling / code-gen consumers
+     *   - a human-readable line appended to the description for Swagger UI
+     */
+    private applyRbac;
+    /**
+     * Build the final OpenAPI document.
+     */
+    build(): IOpenApiDocument;
+    /**
+     * Build the full URL path for a route.
+     */
+    private buildPath;
+    /**
+     * Map SpineJS RouteType to OpenAPI HTTP method string.
+     */
+    private mapRouteType;
+    /**
+     * Build an OpenAPI operation from a route and its documentation.
+     */
+    private buildOperation;
+    /**
+     * Describe the JSON filter envelope used by orm-http's @Filter decorator.
+     *
+     * @Filter accepts either:
+     *   - a Model constructor — @Filterable on its columns stores the filterable
+     *     column map on the model descriptor (Reflect metadata under
+     *     Symbol.for('MODEL_DESCRIPTOR')) at class-load time. We read it directly
+     *     so the schema is available even before orm-http's runtime mixin attaches.
+     *   - an IColumnFilter[] — we build the same envelope shape inline from the
+     *     column descriptors.
+     *
+     * Both cases produce the same { op, filters: [...] } envelope as the runtime
+     * builder in packages/orm-http/src/{model.ts,route-arg.ts}.
+     */
+    private buildFilterSchema;
+    /**
+     * Read the FilterableColumns map from a model constructor via the orm model
+     * descriptor metadata. Keeps http-swagger free of a hard @spinajs/orm dep —
+     * the symbol is global (`Symbol.for('MODEL_DESCRIPTOR')`).
+     */
+    private extractFilterableColumns;
+    /**
+     * Build the { op, filters: [...] } envelope schema given a list of filterable columns.
+     *
+     * OAS 3.0.3 (the doc version we emit) does NOT support multi-type arrays for
+     * `type` — that's an OAS 3.1 feature. Swagger UI renders such schemas as
+     * "Unknown Type: ...". We emit `oneOf` for the Value union and single-typed
+     * sub-schemas for everything else.
+     */
+    private filterEnvelopeSchema;
+    /**
+     * Resolve the effective OpenAPI location for orm-http's @FromModel param.
+     * Mirrors FromDbModel.extract(): paramType decides where the PK is read from
+     * (defaults to path/req.params).
+     */
+    private fromDbModelLocation;
+    /**
+     * Build an OpenAPI parameter from route parameter info.
+     */
+    private buildParameter;
+    /**
+     * Resolve the best schema for a route parameter.
+     * Priority: JSDoc type → decorator schema (param.Schema) → auto-detected primitive (param.RouteParamSchema) → @Schema metadata on DTO class → runtime type inference
+     */
+    private schemaFromParam;
+    /**
+     * Convert a JSON Schema object to an OpenAPI schema, mapping known keywords.
+     */
+    private convertJsonSchema;
+    /**
+     * Build an OpenAPI request body from body-type parameters.
+     */
+    private buildRequestBody;
+    /**
+     * Build response definitions from JSDoc @returns and @response tags.
+     * Only responses explicitly documented in JSDoc are included.
+     */
+    private buildResponses;
+    /**
+     * Lazily register a reusable response component for a standard HTTP status
+     * code (e.g. 401 → `#/components/responses/Unauthorized`) and the shared
+     * Error schema. Returns the component name to $ref, or undefined if the code
+     * isn't in our standard set.
+     *
+     * JSDoc description overrides the default; first JSDoc description wins per
+     * status code so the component stays stable across operations.
+     */
+    private registerStandardResponse;
+    /**
+     * Register the shared Error schema once. Matches the runtime error envelope
+     * built in packages/http/src/error.ts (spread of the Error instance + message,
+     * with optional stack in dev).
+     */
+    private ensureErrorSchema;
+    /**
+     * Infer an OpenAPI schema from a TypeScript runtime type.
+     */
+    private inferSchema;
+    /**
+     * Infer schema from a JSDoc type string like {string}, {number}, {MyDto}
+     */
+    private inferSchemaFromString;
+    /**
+     * Try to parse a string as JSON, return as-is if not valid JSON.
+     */
+    private tryParseJson;
+}
+//# sourceMappingURL=openapi-builder.d.ts.map

package/lib/cjs/openapi-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-builder.d.ts","sourceRoot":"","sources":["../../src/openapi-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,cAAc,EAAqD,MAAM,eAAe,CAAC;AAElG,OAAO,EACL,gBAAgB,EAOhB,kBAAkB,EAClB,cAAc,EAEf,MAAM,iBAAiB,CAAC;AA6FzB,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,QAAQ,CAAmB;IACnC,OAAO,CAAC,IAAI,CAAuC;IACnD,OAAO,CAAC,mBAAmB,CAA0B;IACrD,OAAO,CAAC,qBAAqB,CAAS;IACtC,OAAO,CAAC,kBAAkB,CAA0B;IACpD,OAAO,CAAC,oBAAoB,CAAgB;IAC5C,OAAO,CAAC,mBAAmB,CAAc;gBAE7B,MAAM,EAAE,cAAc;IA2BlC;;OAEG;IACI,aAAa,CAClB,UAAU,EAAE,SAAS,CAAC,cAAc,CAAC,EACrC,QAAQ,EAAE,kBAAkB,GAC3B,IAAI;IAgDP;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa;IAqBrB;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IAe/B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,aAAa;IAMrB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA8B1B;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAqBjB;;OAEG;IACI,KAAK,IAAI,gBAAgB;IAKhC;;OAEG;IACH,OAAO,CAAC,SAAS;IAuBjB;;OAEG;IACH,OAAO,CAAC,YAAY;IAoBpB;;OAEG;IACH,OAAO,CAAC,cAAc;IA4FtB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,iBAAiB;IAuCzB;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IAkBhC;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IAsC5B;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAqB3B;;OAEG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAsCvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA8DzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAgDxB;;;OAGG;IACH,OAAO,CAAC,cAAc;IA2CtB;;;;;;;;OAQG;IACH,OAAO,CAAC,wBAAwB;IAqBhC;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAmBzB;;OAEG;IACH,OAAO,CAAC,WAAW;IAwBnB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAqB7B;;OAEG;IACH,OAAO,CAAC,YAAY;CAQrB"}