@danceroutine/tango-openapi 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pedro Del Moral Lopez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# @danceroutine/tango-openapi
+
+`@danceroutine/tango-openapi` generates OpenAPI 3.1 documents from Tango resource instances. It works best when an application already expresses its HTTP contract through `ModelViewSet`, `GenericAPIView`, or `APIView`.
+
+Applications usually keep a small `openapi.ts` module that instantiates the resources they want to document, passes them through the descriptor helpers, and serves the generated document through Express or Next.js.
+
+## Install
+
+```bash
+pnpm add @danceroutine/tango-openapi
+```
+
+Use this package when you want to:
+
+- generate an OpenAPI 3.1 document from Tango resources
+- derive request and response schemas from Zod-backed resource contracts
+- publish a JSON document to Swagger UI, client generators, or external tooling
+
+## Quick start
+
+```ts
+import { z } from 'zod';
+import {
+    describeAPIView,
+    describeGenericAPIView,
+    describeViewSet,
+    generateOpenAPISpec,
+    type OpenAPISpec,
+} from '@danceroutine/tango-openapi';
+import { HealthAPIView, PostDetailAPIView, PostViewSet } from './resources';
+
+export function createOpenAPISpec(): OpenAPISpec {
+    return generateOpenAPISpec({
+        title: 'Blog API',
+        version: '1.0.0',
+        description: 'OpenAPI document generated from Tango resource instances.',
+        resources: [
+            describeViewSet({
+                basePath: '/api/posts',
+                resource: new PostViewSet(),
+            }),
+            describeGenericAPIView({
+                resource: new PostDetailAPIView(),
+                detailPath: '/api/posts-generic/{id}',
+            }),
+            describeAPIView({
+                path: '/api/healthz',
+                resource: new HealthAPIView(),
+                methods: {
+                    GET: {
+                        summary: 'Health check',
+                        responseSchema: z.object({
+                            status: z.literal('ok'),
+                        }),
+                    },
+                },
+            }),
+        ],
+    });
+}
+```
+
+`describeViewSet()` documents the standard CRUD surface and any custom actions the viewset exposes. `describeGenericAPIView()` documents collection and detail routes for a generic resource. `describeAPIView()` covers fully custom endpoints where application code supplies the operation metadata directly.
+
+The generated object is ready to publish through whichever host framework owns your HTTP layer.
+
+Express:
+
+```ts
+import { createOpenAPISpec } from './openapi';
+
+app.get('/api/openapi.json', (_req, res) => {
+    res.json(createOpenAPISpec());
+});
+```
+
+Next.js App Router:
+
+```ts
+import { createOpenAPISpec } from '@/lib/openapi';
+
+export async function GET(): Promise<Response> {
+    return Response.json(createOpenAPISpec());
+}
+```
+
+## What the generator emits
+
+For a `ModelViewSet`, `generateOpenAPISpec()` emits:
+
+- `GET /<path>`
+- `POST /<path>`
+- `GET /<path>/{id}`
+- `PUT /<path>/{id}`
+- `PATCH /<path>/{id}`
+- `DELETE /<path>/{id}`
+
+When the viewset defines custom actions, the generator also emits those routes using the resolved action paths from the resource itself.
+
+For `GenericAPIView`, the generator documents whichever collection and detail paths the descriptor supplies. For plain `APIView`, the generator uses the manual operation metadata passed to `describeAPIView()`.
+
+The package also generates component schemas from Tango model metadata and Zod schemas when those are available through the resource contract.
+
+## Current boundary
+
+The package documents Tango resources directly and covers the built-in CRUD surface, generic view routes, and custom action paths. Richer custom action request and response details still come from explicit overrides, and plain `APIView` routes still need manual method metadata because Tango cannot infer those HTTP contracts from the class alone.
+
+`generateSchemaFromModel()` and `generateSchemaFromZod()` remain useful when an application needs schema generation outside full document generation.
+
+## Public API
+
+The root export includes:
+
+- `generateOpenAPISpec()`
+- `describeViewSet()`
+- `describeGenericAPIView()`
+- `describeAPIView()`
+- `generateSchemaFromModel()`
+- `generateSchemaFromZod()`
+- `mapTypeToOpenAPI()`
+
+The root export is enough for normal application use. The `domain`, `generators`, and `mappers` subpaths are useful when you want a narrower import boundary.
+
+## Documentation
+
+- Official documentation: <https://tangowebframework.dev>
+- Publish an OpenAPI document: <https://tangowebframework.dev/how-to/publish-openapi-document>
+- OpenAPI API reference: <https://tangowebframework.dev/reference/openapi-api>
+- Resources topic: <https://tangowebframework.dev/topics/resources-and-viewsets>
+
+## Development
+
+```bash
+pnpm --filter @danceroutine/tango-openapi build
+pnpm --filter @danceroutine/tango-openapi typecheck
+pnpm --filter @danceroutine/tango-openapi test
+```
+
+For the wider contributor workflow, use:
+
+- <https://tangowebframework.dev/contributing>
+
+## License
+
+MIT

package/dist/chunk-BkvOhyD0.js

@@ -0,0 +1,12 @@
+
+//#region rolldown:runtime
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+};
+
+//#endregion
+export { __export };

package/dist/domain/describeResources.d.ts

@@ -0,0 +1,10 @@
+import type { APIViewMethod, ModelSerializerClass, SerializerSchema } from '@danceroutine/tango-resources';
+import type { OpenAPIViewSetDescriptor, OpenAPIGenericAPIViewDescriptor, OpenAPIAPIViewDescriptor } from './types';
+export declare function describeViewSet(descriptor: Omit<OpenAPIViewSetDescriptor, 'kind'>): OpenAPIViewSetDescriptor;
+export declare function describeViewSet<TModel extends Record<string, unknown>, TSerializer extends ModelSerializerClass<TModel, SerializerSchema, SerializerSchema, SerializerSchema>>(descriptor: Omit<OpenAPIViewSetDescriptor<TModel, TSerializer>, 'kind'>): OpenAPIViewSetDescriptor<TModel, TSerializer>;
+export declare function describeGenericAPIView(descriptor: Omit<OpenAPIGenericAPIViewDescriptor, 'kind'>): OpenAPIGenericAPIViewDescriptor;
+export declare function describeGenericAPIView<TModel extends Record<string, unknown>, TSerializer extends ModelSerializerClass<TModel, SerializerSchema, SerializerSchema, SerializerSchema>>(descriptor: Omit<OpenAPIGenericAPIViewDescriptor<TModel, TSerializer>, 'kind'>): OpenAPIGenericAPIViewDescriptor<TModel, TSerializer>;
+export declare function describeAPIView(descriptor: Omit<OpenAPIAPIViewDescriptor, 'kind'>): OpenAPIAPIViewDescriptor;
+export declare function describeAPIView<TMethods extends Partial<Record<APIViewMethod, OpenAPIAPIViewDescriptor['methods'][APIViewMethod]>>>(descriptor: Omit<OpenAPIAPIViewDescriptor, 'kind'> & {
+    methods: TMethods;
+}): OpenAPIAPIViewDescriptor;

package/dist/domain/index.d.ts

@@ -1,4 +1,5 @@
 /**
  * Domain boundary barrel: centralizes this subdomain's public contract.
  */
-export type { ComponentsObject, MediaTypeObject, OperationObject, OpenAPIModel, OpenAPIModelFieldMeta, OpenAPIOptions, OpenAPISpec, OpenAPIGeneratorConfig, ParameterObject, PathItemObject, ReferenceObject, RequestBodyObject, ResponseObject, SchemaObject, ViewSetLike, } from './types';
+export type { ComponentsObject, MediaTypeObject, OperationObject, OpenAPIAPIViewDescriptor, OpenAPIModel, OpenAPIModelFieldMeta, OpenAPIOptions, OpenAPIOperationOverride, OpenAPIResponseOverride, OpenAPIResourceDescriptor, OpenAPISchemaInput, OpenAPISpec, OpenAPIGeneratorConfig, OpenAPIGenericAPIViewDescriptor, OpenAPIViewSetDescriptor, ParameterObject, PathItemObject, ReferenceObject, RequestBodyObject, ResponseObject, SchemaObject, } from './types';
+export { describeAPIView, describeGenericAPIView, describeViewSet } from './describeResources';

package/dist/domain/index.js

@@ -1,4 +1,3 @@
-/**
- * Domain boundary barrel: centralizes this subdomain's public contract.
- */
-export {};
+import { describeAPIView, describeGenericAPIView, describeViewSet } from "../domain-B-7sApJT.js";
+
+export { describeAPIView, describeGenericAPIView, describeViewSet };

package/dist/domain/types.d.ts

@@ -1,4 +1,6 @@
+import type { APIView, APIViewMethod, GenericAPIView, ModelSerializerClass, ModelViewSet, SerializerSchema } from '@danceroutine/tango-resources';
 import type { z } from 'zod';
+/** Model field metadata used by low-level model-to-schema OpenAPI generation. */
 export type OpenAPIModelFieldMeta = {
     type: string;
     description?: string;
@@ -6,61 +8,99 @@ export type OpenAPIModelFieldMeta = {
     default?: unknown;
     primaryKey?: boolean;
 };
+/** Minimal model shape consumed by low-level OpenAPI mappers. */
 export type OpenAPIModel = {
     name: string;
     fields: Record<string, OpenAPIModelFieldMeta>;
 };
-export type ViewSetLike = {
-    repository?: {
-        model?: OpenAPIModel;
-    };
-};
+/** OpenAPI `$ref` object. */
 export type ReferenceObject = {
     $ref: string;
 };
+/** OpenAPI schema object subset used by Tango. */
 export type SchemaObject = {
     type?: string;
     description?: string;
     nullable?: boolean;
     default?: unknown;
-    properties?: Record<string, SchemaObject>;
+    properties?: Record<string, SchemaObject | ReferenceObject>;
     required?: string[];
     items?: SchemaObject | ReferenceObject;
+    additionalProperties?: boolean | SchemaObject | ReferenceObject;
+    enum?: unknown[];
+    oneOf?: Array<SchemaObject | ReferenceObject>;
+    anyOf?: Array<SchemaObject | ReferenceObject>;
+    allOf?: Array<SchemaObject | ReferenceObject>;
+    format?: string;
+    [key: string]: unknown;
 };
+/** Schema inputs accepted by resource-aware OpenAPI descriptors. */
+export type OpenAPISchemaInput = z.ZodType | SchemaObject | ReferenceObject;
+/** OpenAPI media type object. */
 export type MediaTypeObject = {
     schema: SchemaObject | ReferenceObject;
 };
+/** OpenAPI response object. */
 export type ResponseObject = {
     description: string;
     content?: Record<string, MediaTypeObject>;
 };
+/** OpenAPI parameter object. */
 export type ParameterObject = {
     name: string;
     in: 'query' | 'path' | 'header' | 'cookie';
     required?: boolean;
-    schema: SchemaObject;
+    schema: SchemaObject | ReferenceObject;
+    description?: string;
 };
+/** OpenAPI request body object. */
 export type RequestBodyObject = {
     required?: boolean;
     content: Record<string, MediaTypeObject>;
 };
+/** OpenAPI operation object subset. */
 export type OperationObject = {
     summary?: string;
+    description?: string;
     tags?: string[];
     parameters?: ParameterObject[];
     requestBody?: RequestBodyObject;
     responses: Record<string, ResponseObject>;
 };
+/** Override shape for one explicit response. */
+export type OpenAPIResponseOverride = {
+    description: string;
+    schema?: OpenAPISchemaInput;
+};
+/** Override shape for one operation. */
+export type OpenAPIOperationOverride = {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    parameters?: ParameterObject[];
+    requestBody?: {
+        required?: boolean;
+        schema: OpenAPISchemaInput;
+    };
+    responseStatus?: string;
+    responseDescription?: string;
+    responseSchema?: OpenAPISchemaInput;
+    responses?: Record<string, OpenAPIResponseOverride>;
+};
+/** OpenAPI path item object subset. */
 export type PathItemObject = {
     get?: OperationObject;
     post?: OperationObject;
+    put?: OperationObject;
     patch?: OperationObject;
     delete?: OperationObject;
 };
+/** OpenAPI components object subset. */
 export type ComponentsObject = {
     schemas?: Record<string, SchemaObject>;
     securitySchemes?: Record<string, Record<string, unknown>>;
 };
+/** Root OpenAPI specification document shape. */
 export interface OpenAPISpec {
     openapi: string;
     info: {
@@ -75,6 +115,7 @@ export interface OpenAPISpec {
     paths: Record<string, PathItemObject>;
     components?: ComponentsObject;
 }
+/** Options for generating an OpenAPI spec document. */
 export interface OpenAPIOptions {
     title: string;
     version: string;
@@ -84,10 +125,33 @@ export interface OpenAPIOptions {
         description?: string;
     }>;
 }
+export type OpenAPIViewSetDescriptor<TModel extends Record<string, unknown> = Record<string, unknown>, TSerializer extends ModelSerializerClass<TModel, SerializerSchema, SerializerSchema, SerializerSchema> = ModelSerializerClass<TModel, SerializerSchema, SerializerSchema, SerializerSchema>> = {
+    kind: 'viewset';
+    basePath: string;
+    resource: ModelViewSet<TModel, TSerializer>;
+    tags?: string[];
+    actions?: Record<string, OpenAPIOperationOverride>;
+};
+export type OpenAPIGenericAPIViewDescriptor<TModel extends Record<string, unknown> = Record<string, unknown>, TSerializer extends ModelSerializerClass<TModel, SerializerSchema, SerializerSchema, SerializerSchema> = ModelSerializerClass<TModel, SerializerSchema, SerializerSchema, SerializerSchema>> = {
+    kind: 'generic';
+    collectionPath?: string;
+    detailPath?: string;
+    resource: GenericAPIView<TModel, TSerializer>;
+    tags?: string[];
+    methods?: Partial<Record<APIViewMethod, OpenAPIOperationOverride>>;
+};
+export type OpenAPIAPIViewDescriptor = {
+    kind: 'api';
+    path: string;
+    resource: APIView;
+    tags?: string[];
+    methods: Partial<Record<APIViewMethod, OpenAPIOperationOverride>>;
+};
+type AnyOpenAPIViewSetDescriptor = OpenAPIViewSetDescriptor<any, any>;
+type AnyOpenAPIGenericAPIViewDescriptor = OpenAPIGenericAPIViewDescriptor<any, any>;
+export type OpenAPIResourceDescriptor = AnyOpenAPIViewSetDescriptor | AnyOpenAPIGenericAPIViewDescriptor | OpenAPIAPIViewDescriptor;
+/** Extended generator configuration used by Tango's OpenAPI builder. */
 export type OpenAPIGeneratorConfig = OpenAPIOptions & {
-    resources?: Array<{
-        path: string;
-        schema: z.ZodType;
-    }>;
-    viewsets?: Record<string, ViewSetLike>;
+    resources?: OpenAPIResourceDescriptor[];
 };
+export {};

package/dist/domain-B-7sApJT.js

@@ -0,0 +1,34 @@
+import { __export } from "./chunk-BkvOhyD0.js";
+
+//#region src/domain/describeResources.ts
+function describeViewSet(descriptor) {
+	return {
+		kind: "viewset",
+		...descriptor
+	};
+}
+function describeGenericAPIView(descriptor) {
+	return {
+		kind: "generic",
+		...descriptor
+	};
+}
+function describeAPIView(descriptor) {
+	return {
+		kind: "api",
+		...descriptor
+	};
+}
+
+//#endregion
+//#region src/domain/index.ts
+var domain_exports = {};
+__export(domain_exports, {
+	describeAPIView: () => describeAPIView,
+	describeGenericAPIView: () => describeGenericAPIView,
+	describeViewSet: () => describeViewSet
+});
+
+//#endregion
+export { describeAPIView, describeGenericAPIView, describeViewSet, domain_exports };
+//# sourceMappingURL=domain-B-7sApJT.js.map

package/dist/domain-B-7sApJT.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-B-7sApJT.js","names":["descriptor: Omit<OpenAPIViewSetDescriptor, 'kind'>","descriptor: Omit<OpenAPIGenericAPIViewDescriptor, 'kind'>","descriptor: Omit<OpenAPIAPIViewDescriptor, 'kind'>"],"sources":["../src/domain/describeResources.ts","../src/domain/index.ts"],"sourcesContent":["import type { APIViewMethod, ModelSerializerClass, SerializerSchema } from '@danceroutine/tango-resources';\nimport type { OpenAPIViewSetDescriptor, OpenAPIGenericAPIViewDescriptor, OpenAPIAPIViewDescriptor } from './types';\n\nexport function describeViewSet(descriptor: Omit<OpenAPIViewSetDescriptor, 'kind'>): OpenAPIViewSetDescriptor;\nexport function describeViewSet<\n    TModel extends Record<string, unknown>,\n    TSerializer extends ModelSerializerClass<TModel, SerializerSchema, SerializerSchema, SerializerSchema>,\n>(\n    descriptor: Omit<OpenAPIViewSetDescriptor<TModel, TSerializer>, 'kind'>\n): OpenAPIViewSetDescriptor<TModel, TSerializer>;\nexport function describeViewSet(descriptor: Omit<OpenAPIViewSetDescriptor, 'kind'>) {\n    return {\n        kind: 'viewset',\n        ...descriptor,\n    };\n}\n\nexport function describeGenericAPIView(\n    descriptor: Omit<OpenAPIGenericAPIViewDescriptor, 'kind'>\n): OpenAPIGenericAPIViewDescriptor;\nexport function describeGenericAPIView<\n    TModel extends Record<string, unknown>,\n    TSerializer extends ModelSerializerClass<TModel, SerializerSchema, SerializerSchema, SerializerSchema>,\n>(\n    descriptor: Omit<OpenAPIGenericAPIViewDescriptor<TModel, TSerializer>, 'kind'>\n): OpenAPIGenericAPIViewDescriptor<TModel, TSerializer>;\nexport function describeGenericAPIView(descriptor: Omit<OpenAPIGenericAPIViewDescriptor, 'kind'>) {\n    return {\n        kind: 'generic',\n        ...descriptor,\n    };\n}\n\nexport function describeAPIView(descriptor: Omit<OpenAPIAPIViewDescriptor, 'kind'>): OpenAPIAPIViewDescriptor;\nexport function describeAPIView<\n    TMethods extends Partial<Record<APIViewMethod, OpenAPIAPIViewDescriptor['methods'][APIViewMethod]>>,\n>(descriptor: Omit<OpenAPIAPIViewDescriptor, 'kind'> & { methods: TMethods }): OpenAPIAPIViewDescriptor;\nexport function describeAPIView(descriptor: Omit<OpenAPIAPIViewDescriptor, 'kind'>) {\n    return {\n        kind: 'api',\n        ...descriptor,\n    };\n}\n","/**\n * Domain boundary barrel: centralizes this subdomain's public contract.\n */\n\nexport type {\n    ComponentsObject,\n    MediaTypeObject,\n    OperationObject,\n    OpenAPIAPIViewDescriptor,\n    OpenAPIModel,\n    OpenAPIModelFieldMeta,\n    OpenAPIOptions,\n    OpenAPIOperationOverride,\n    OpenAPIResponseOverride,\n    OpenAPIResourceDescriptor,\n    OpenAPISchemaInput,\n    OpenAPISpec,\n    OpenAPIGeneratorConfig,\n    OpenAPIGenericAPIViewDescriptor,\n    OpenAPIViewSetDescriptor,\n    ParameterObject,\n    PathItemObject,\n    ReferenceObject,\n    RequestBodyObject,\n    ResponseObject,\n    SchemaObject,\n} from './types';\nexport { describeAPIView, describeGenericAPIView, describeViewSet } from './describeResources';\n"],"mappings":";;;AAUO,SAAS,gBAAgBA,YAAoD;AAChF,QAAO;EACH,MAAM;EACN,GAAG;CACN;AACJ;AAWM,SAAS,uBAAuBC,YAA2D;AAC9F,QAAO;EACH,MAAM;EACN,GAAG;CACN;AACJ;AAMM,SAAS,gBAAgBC,YAAoD;AAChF,QAAO;EACH,MAAM;EACN,GAAG;CACN;AACJ"}

package/dist/generators/index.js

@@ -1,4 +1,4 @@
-import "../schema-DVxdID48.js";
-import { generateOpenAPISpec, spec_exports } from "../generators-Bvwyyja4.js";
+import "../schema-D3ybOrpr.js";
+import { generateOpenAPISpec, spec_exports } from "../generators-JMALItMS.js";
 
 export { generateOpenAPISpec, spec_exports as spec };

package/dist/generators/spec/generateOpenAPISpec.d.ts

@@ -1,2 +1,5 @@
 import type { OpenAPIGeneratorConfig, OpenAPISpec } from '../../domain';
+/**
+ * Build an OpenAPI 3.1 document from Tango resource configuration.
+ */
 export declare function generateOpenAPISpec(config: OpenAPIGeneratorConfig): OpenAPISpec;