@nestia/sdk 14.0.0 → 14.0.2

package/src/generates/internal/SwaggerOperationComposer.ts

@@ -8,7 +8,25 @@ import { SwaggerDescriptionComposer } from "./SwaggerDescriptionComposer";
 import { SwaggerOperationParameterComposer } from "./SwaggerOperationParameterComposer";
 import { SwaggerOperationResponseComposer } from "./SwaggerOperationResponseComposer";
 
+/**
+ * Composes the operation object of a route.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace collects tags, security, parameters, and responses.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The document's own tag list is edited only by adding.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerOperationComposer composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SwaggerOperationComposer {
+  /**
+   * Returns the operation of a route, registering its tags in the document.
+   *
+   * @evidence contracts/common.md#principled-implementation The tags are the controller's, the route's, and the `@tag` comments, each registered once with the first description, and the security is merged from the controller, the route, and the `@security` comments.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A tag's description is never overwritten.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerOperationComposer.compose composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const compose = (props: {
     config: Omit<INestiaConfig.ISwaggerConfig, "output">;
     document: OpenApi.IDocument;
@@ -22,7 +40,7 @@ export namespace SwaggerOperationComposer {
       ...SwaggerDescriptionComposer.getJsDocTexts({
         jsDocTags: props.route.jsDocTags,
         name: "tag",
-      }).map((t) => t.split(" ")[0]!),
+      }).map((t) => t.trim().split(/\s+/)[0]!),
     ]);
     if (tags.size) {
       props.document.tags ??= [];
@@ -33,11 +51,13 @@ export namespace SwaggerOperationComposer {
         jsDocTags: props.route.jsDocTags,
         name: "tag",
       })) {
-        const [name, ...description] = texts.split(" ");
+        // the name is the first word; a tag's text may run over lines
+        const name: string = texts.trim().split(/\s+/)[0]!;
+        const description: string = texts.trim().substring(name.length).trim();
         if (description.length)
           props.document.tags.find(
             (elem) => elem.name === name,
-          )!.description ??= description.join(" ");
+          )!.description ??= description;
       }
     }
 
@@ -52,8 +72,7 @@ export namespace SwaggerOperationComposer {
             ? [{}]
             : tag.text.map((text) => {
                 const line: string[] = text.text
-                  .split(" ")
-                  .filter((s) => s.trim())
+                  .split(/\s+/)
                   .filter((s) => !!s.length);
                 if (line.length === 0) return {};
                 return {
@@ -79,7 +98,7 @@ export namespace SwaggerOperationComposer {
         props.route.operationId ??
         props.config.operationId?.({
           class: props.route.controller.class.name,
-          function: props.route.name,
+          function: props.route.key,
           method: props.route.method as "GET",
           path: props.route.path,
         }),
@@ -87,6 +106,7 @@ export namespace SwaggerOperationComposer {
         ...props.route.pathParameters,
         ...props.route.queryParameters,
         ...(props.route.queryObject ? [props.route.queryObject] : []),
+        ...props.route.headerParameters,
         ...(props.route.headerObject ? [props.route.headerObject] : []),
       ]
         .map((p) =>
@@ -101,6 +121,7 @@ export namespace SwaggerOperationComposer {
         .flat(),
       requestBody: writeRequestBody(props),
       responses: SwaggerOperationResponseComposer.compose({
+        config: props.config,
         schema: props.schema,
         route: props.route,
       }),
@@ -108,6 +129,13 @@ export namespace SwaggerOperationComposer {
       ...(props.route.extensions ?? {}),
       "x-samchon-accessor": props.route.accessor,
       "x-samchon-controller": props.route.controller.class.name,
+      ...(props.config.additional === true
+        ? {
+            "x-nestia-method": props.route.method,
+            "x-nestia-namespace": props.route.accessor.join("."),
+            "x-nestia-jsDocTags": props.route.jsDocTags,
+          }
+        : {}),
     };
   };
 }
@@ -135,6 +163,8 @@ export namespace SwaggerOperationComposer {
  * helper across two rules that disagree would trade one defect for another.
  */
 const writeRequestBody = (props: {
+  config: Omit<INestiaConfig.ISwaggerConfig, "output">;
+  document: OpenApi.IDocument;
   schema: (metadata: MetadataSchema) => OpenApi.IJsonSchema | undefined;
   route: ITypedHttpRoute;
 }): OpenApi.IOperation.IRequestBody | undefined => {
@@ -144,6 +174,8 @@ const writeRequestBody = (props: {
   );
   if (schema === undefined) return undefined;
   return SwaggerOperationParameterComposer.body({
+    config: props.config,
+    document: props.document,
     schema,
     jsDocTags: props.route.jsDocTags,
     parameter: props.route.body,

package/src/generates/internal/SwaggerOperationParameterComposer.ts

@@ -1,4 +1,5 @@
 import { OpenApi } from "@typia/interface";
+import { OpenApiTypeChecker } from "@typia/utils";
 import { VariadicSingleton } from "tstl";
 import { IJsDocTagInfo, IJsonSchemaCollection } from "typia";
 
@@ -6,13 +7,33 @@ import { INestiaConfig } from "../../INestiaConfig";
 import {
   JsonSchemasProgrammer,
   MetadataObjectType,
+  MetadataProperty,
   isRequiredOf,
+  isSoleLiteralOf,
 } from "../../internal/legacy";
 import { ITypedHttpRouteParameter } from "../../structures/ITypedHttpRouteParameter";
 import { SwaggerDescriptionComposer } from "./SwaggerDescriptionComposer";
-import { SwaggerReadonlyArrayEmender } from "./SwaggerReadonlyArrayEmender";
 
+/**
+ * Composes the parameters and the request body of an operation.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace writes each parameter where the router reads it, decomposes a query or headers object into its keys where the format needs it, and fits a body into what Swagger 2.0 can hold.
+ * @evidence contracts/common.md#clear-and-simple-design Two public functions over private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The 2.0 restrictions are applied by dedicated helpers.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerOperationParameterComposer composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SwaggerOperationParameterComposer {
+  /**
+   * The inputs of a parameter's composition: the configuration, the document,
+   * the route's comment tags, the parameter, and its schema.
+   *
+   * @evidence contracts/common.md#principled-implementation The record is the argument of every composer.
+   * @evidence contracts/common.md#clear-and-simple-design A flat record.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerOperationParameterComposer.IProps composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IProps<Parameter extends ITypedHttpRouteParameter> {
     config: Omit<INestiaConfig.ISwaggerConfig, "output">;
     document: OpenApi.IDocument;
@@ -21,6 +42,15 @@ export namespace SwaggerOperationParameterComposer {
     parameter: Parameter;
   }
 
+  /**
+   * Returns the parameter objects of a path, query, or header parameter.
+   *
+   * @evidence contracts/common.md#principled-implementation A query object or a headers object is decomposed into one parameter per property where the format needs it.
+   * @evidence contracts/common.md#clear-and-simple-design One dispatch by category.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The category decides the location.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerOperationParameterComposer.compose composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const compose = (
     props: IProps<ITypedHttpRouteParameter>,
   ): OpenApi.IOperation.IParameter[] =>
@@ -32,9 +62,20 @@ export namespace SwaggerOperationParameterComposer {
           ? query({ ...props, parameter: props.parameter })
           : header({ ...props, parameter: props.parameter });
 
+  /**
+   * Returns the request body of a route, or `undefined`.
+   *
+   * Swagger 2.0 receives the form a body parameter can hold.
+   *
+   * @evidence contracts/common.md#principled-implementation The description carries the encryption warning, and the flag is written for the versions that can hold it.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The 2.0 conversion is separate.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerOperationParameterComposer.body composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const body = (
-    props: Omit<IProps<ITypedHttpRouteParameter.IBody>, "config" | "document">,
-  ): OpenApi.IOperation.IRequestBody => {
+    props: IProps<ITypedHttpRouteParameter.IBody>,
+  ): OpenApi.IOperation.IRequestBody | undefined => {
     const description: string | undefined =
       props.parameter.description ??
       SwaggerDescriptionComposer.descriptionFromJsDocTag({
@@ -42,7 +83,7 @@ export namespace SwaggerOperationParameterComposer {
         tag: "param",
         parameter: props.parameter.name,
       });
-    return {
+    const output: OpenApi.IOperation.IRequestBody = {
       description: props.parameter.encrypted
         ? `${warning.get(!!description)}${description ?? ""}`
         : description,
@@ -56,6 +97,68 @@ export namespace SwaggerOperationParameterComposer {
       required: props.parameter.metadata.required,
       ...(props.parameter.encrypted ? { "x-nestia-encrypted": true } : {}),
     };
+    return props.config.openapi === "2.0"
+      ? swaggerV2Body(props, output)
+      : output;
+  };
+
+  /**
+   * The request body a Swagger 2.0 document can hold.
+   *
+   * Typia's downgrader refuses what 2.0 has no place for rather than lose it,
+   * so one route used to fail the whole document (#1649). A 2.0 body parameter
+   * holds only a schema: no example, and no `x-nestia-encrypted` flag, whose
+   * warning the description keeps. A form becomes one `formData` parameter per
+   * field, which carry neither the body's description nor the form object's own
+   * attributes, and are each required or not; so a form keeps only its fields,
+   * is required when one of them is, and without fields has no body to list. A
+   * `formData` file is one file, never an array, a union, or null, so a field
+   * taking several files, or none, is listed as one file, optional unless it
+   * requires one ({@link swaggerV2FormField}).
+   */
+  const swaggerV2Body = (
+    props: IProps<ITypedHttpRouteParameter.IBody>,
+    body: OpenApi.IOperation.IRequestBody,
+  ): OpenApi.IOperation.IRequestBody | undefined => {
+    const contentType: string = props.parameter.contentType;
+    if (
+      contentType !== "multipart/form-data" &&
+      contentType !== "application/x-www-form-urlencoded"
+    )
+      return {
+        description: body.description,
+        content: { [contentType]: { schema: props.schema } },
+        required: body.required,
+      };
+    const object: OpenApi.IJsonSchema.IObject | undefined = resolveObject(
+      props.document,
+      props.schema,
+    );
+    if (
+      object === undefined ||
+      Object.keys(object.properties ?? {}).length === 0
+    )
+      return undefined;
+    const fields: [string, ISwaggerV2FormField][] = Object.entries(
+      object.properties ?? {},
+    ).map(([key, value]) => [key, swaggerV2FormField(value)]);
+    const required: string[] = (object.required ?? []).filter(
+      (key) => fields.find(([name]) => name === key)?.[1].optional !== true,
+    );
+    return {
+      content: {
+        [contentType]: {
+          schema: {
+            type: "object",
+            properties: Object.fromEntries(
+              fields.map(([key, field]) => [key, field.schema]),
+            ),
+            required,
+          },
+        },
+      },
+      required: required.length !== 0,
+    };
   };
 
   const path = (
@@ -103,48 +206,71 @@ export namespace SwaggerOperationParameterComposer {
       ITypedHttpRouteParameter.IHeaders | ITypedHttpRouteParameter.IQuery
     >,
   ): OpenApi.IOperation.IParameter[] => {
+    const object: MetadataObjectType | undefined = props.parameter.metadata
+      .objects[0]?.type as MetadataObjectType | undefined;
     const param: OpenApi.IOperation.IParameter = {
       name: props.parameter.field ?? props.parameter.name,
       in: props.parameter.category === "query" ? "query" : "header",
       schema: props.schema,
       description: parameterDescription(props),
-      required: props.parameter.metadata.required,
+      // An unnamed object's keys are the request's own query keys or headers,
+      // so it is mandatory only when one of the keys the document describes
+      // is; an object whose described properties are all optional is satisfied
+      // when the request sends none of them. A field-named parameter is one
+      // key, required as declared.
+      required:
+        props.parameter.metadata.required &&
+        (props.parameter.field !== null ||
+          (object?.properties.some(
+            (p) => isDescribed(p) && isRequiredOf(p.value),
+          ) ??
+            true)),
       example: props.parameter.example,
       examples: props.parameter.examples,
     };
+    // A field-named parameter is one key, which typia's HTTP rules (#1648)
+    // keep atomic, and a query or headers object passed them: one object of
+    // statically named atomic or array-of-atomic properties, so each has a
+    // name to give its parameter.
+    if (props.parameter.field !== null || object === undefined) return [param];
+    // `decompose: false` keeps a query object one parameter where the format
+    // can say so: OpenAPI 3.x spreads it into its keys with `style: form` and
+    // `explode: true`. Swagger 2.0 has no object query parameter, and no
+    // format spreads an object into headers, so one parameter would be a key
+    // or header no request carries (#1653); those are always decomposed.
     if (
-      props.config.decompose === false ||
-      props.parameter.metadata.objects.length === 0
+      props.config.decompose === false &&
+      props.parameter.category === "query" &&
+      props.config.openapi !== "2.0"
     )
-      return [param];
-    return (
-      props.parameter.metadata.objects[0]!.type as MetadataObjectType
-    ).properties
-      .filter((p) =>
-        p.jsDocTags.every(
-          (tag) => tag.name !== "hidden" && tag.name !== "ignore",
-        ),
-      )
-      .map((p) => {
-        const json: IJsonSchemaCollection = JsonSchemasProgrammer.writeSchemas({
-          version: "3.1",
-          metadatas: [p.value],
-        }) as IJsonSchemaCollection;
-        SwaggerReadonlyArrayEmender.emend({
-          components: json.components,
-          schema: json.schemas[0],
-          metadata: p.value,
-        });
-        if (Object.keys(json.components.schemas ?? {}).length !== 0) {
-          props.document.components ??= {};
-          props.document.components.schemas ??= {};
-          Object.assign(
-            props.document.components.schemas,
-            json.components.schemas,
-          );
-        }
+      return [{ ...param, style: "form", explode: true }];
+    // One parameter per property typia's object schema describes, so the
+    // decomposed form says what `decompose: false` would say about the object:
+    // the property's schema, and in the parameter's own fields its
+    // description, deprecation, and share of the object's examples.
+    return object.properties
+      .filter(isDescribed)
+      .map((p): IDecomposedParameter | null => {
+        const key: string = String(p.key.constants[0]!.values[0]!.value);
+        const json: IJsonSchemaCollection | null =
+          JsonSchemasProgrammer.writeProperty({
+            version: "3.1",
+            metadata: props.parameter.metadata,
+            key,
+            value: p.value,
+          });
+        if (json === null) return null;
+        // Only what the document lacks: the parameter's own schema already
+        // brought every component its properties reach from the native bake.
+        // Existing document components take precedence over this copy.
+        props.document.components ??= {};
+        props.document.components.schemas ??= {};
+        for (const [name, schema] of Object.entries(
+          json.components.schemas ?? {},
+        ))
+          props.document.components.schemas[name] ??= schema;
         return {
-          name: p.key.constants[0]!.values[0]!.value as string,
+          name: key,
           in: props.parameter.category === "query" ? "query" : "header",
           schema: json.schemas[0]!,
           required: isRequiredOf(p.value),
@@ -153,11 +279,167 @@ export namespace SwaggerOperationParameterComposer {
             jsDocTags: p.jsDocTags,
             kind: "title",
           }).description,
+          // Swagger 2.0 defines no `deprecated` on a parameter, and the
+          // downgrader copies the field through rather than refusing it.
+          deprecated:
+            props.config.openapi !== "2.0" &&
+            p.jsDocTags.some((tag) => tag.name === "deprecated")
+              ? true
+              : undefined,
+          example: memberOf(props.parameter.example, key),
+          examples: membersOf(props.parameter.examples, key),
         };
-      });
+      })
+      .filter((p): p is IDecomposedParameter => p !== null);
+  };
+}
+
+/**
+ * A decomposed parameter. OpenAPI 3.0 through 3.2 define `deprecated` on the
+ * Parameter Object, which typia's `OpenApi.IOperation.IParameter` does not
+ * model; its 3.x downgraders carry the field through unchanged.
+ */
+type IDecomposedParameter = OpenApi.IOperation.IParameter & {
+  deprecated?: boolean;
+};
+
+/**
+ * Whether the document can describe a property on its own: it has a literal key
+ * to name it, and none of the `@hidden`, `@ignore`, and `@internal` tags
+ * typia's object schema drops it for.
+ */
+const isDescribed = (p: MetadataProperty): boolean =>
+  isSoleLiteralOf(p.key) &&
+  p.jsDocTags.every(
+    (tag) =>
+      tag.name !== "hidden" && tag.name !== "ignore" && tag.name !== "internal",
+  );
+
+/** A form field as a Swagger 2.0 `formData` parameter holds it. */
+interface ISwaggerV2FormField {
+  schema: OpenApi.IJsonSchema;
+
+  /** Whether a request may leave the field out though its type requires it. */
+  optional: boolean;
+}
+
+/**
+ * A form field as a Swagger 2.0 `formData` parameter can hold it.
+ *
+ * A 2.0 file is one file: never an array, a union, or null. A field whose value
+ * is made of files, a union of files or one of them or null, or an array of
+ * those, becomes the one file a request may carry, keeping the field's title,
+ * description, and deprecation. A request may then carry none, since the server
+ * reads a missing field as null or an empty array, so such a field is not
+ * required unless its array requires an item; a plain file is kept as it is.
+ */
+const swaggerV2FormField = (
+  schema: OpenApi.IJsonSchema,
+): ISwaggerV2FormField => {
+  const file: IFileOf | undefined = fileOf(schema, true);
+  if (file === undefined || file.binary === schema)
+    return { schema, optional: false };
+  const attributes = schema as OpenApi.IJsonSchema.IString;
+  return {
+    schema: {
+      ...file.binary,
+      ...(attributes.title !== undefined ? { title: attributes.title } : {}),
+      ...(attributes.description !== undefined
+        ? { description: attributes.description }
+        : {}),
+      ...(attributes.deprecated !== undefined
+        ? { deprecated: attributes.deprecated }
+        : {}),
+    },
+    optional: file.optional,
   };
+};
+
+interface IFileOf {
+  binary: OpenApi.IJsonSchema;
+  optional: boolean;
 }
 
+/** The file a field's value is made of, if it is made of files only. */
+const fileOf = (
+  schema: OpenApi.IJsonSchema,
+  top: boolean,
+): IFileOf | undefined => {
+  if (isBinary(schema)) return { binary: schema, optional: false };
+  if (OpenApiTypeChecker.isOneOf(schema)) {
+    const members: OpenApi.IJsonSchema[] = schema.oneOf.filter(
+      (s) => OpenApiTypeChecker.isNull(s) === false,
+    );
+    const files: Array<IFileOf | undefined> = members.map((s) =>
+      fileOf(s, top),
+    );
+    if (files.length === 0 || files.some((f) => f === undefined))
+      return undefined;
+    return {
+      binary: files[0]!.binary,
+      optional:
+        members.length !== schema.oneOf.length ||
+        files.some((f) => f!.optional),
+    };
+  }
+  if (top && OpenApiTypeChecker.isArray(schema)) {
+    const item: IFileOf | undefined = fileOf(schema.items, false);
+    // an empty array is a request without the field, unless one file is due
+    return item === undefined
+      ? undefined
+      : { binary: item.binary, optional: (schema.minItems ?? 0) === 0 };
+  }
+  return undefined;
+};
+
+const isBinary = (schema: OpenApi.IJsonSchema): boolean =>
+  OpenApiTypeChecker.isString(schema) && schema.format === "binary";
+
+/** The object schema `schema` is or refers to, if it is one. */
+const resolveObject = (
+  document: OpenApi.IDocument,
+  schema: OpenApi.IJsonSchema,
+): OpenApi.IJsonSchema.IObject | undefined => {
+  const visited: Set<string> = new Set();
+  while (OpenApiTypeChecker.isReference(schema)) {
+    if (visited.has(schema.$ref)) return undefined;
+    visited.add(schema.$ref);
+    const next: OpenApi.IJsonSchema | undefined =
+      document.components?.schemas?.[
+        schema.$ref.substring("#/components/schemas/".length)
+      ];
+    if (next === undefined) return undefined;
+    schema = next;
+  }
+  return OpenApiTypeChecker.isObject(schema) ? schema : undefined;
+};
+
+/** The `key` member of an object example, if the example has one. */
+const memberOf = (example: unknown, key: string): unknown =>
+  typeof example === "object" &&
+  example !== null &&
+  Object.prototype.hasOwnProperty.call(example, key)
+    ? (example as Record<string, unknown>)[key]
+    : undefined;
+
+/**
+ * Named object examples narrowed to the ones whose value has a `key` member,
+ * each an Example Object of that member.
+ */
+const membersOf = (
+  examples: Record<string, OpenApi.IExample> | undefined,
+  key: string,
+): Record<string, OpenApi.IExample> | undefined => {
+  if (examples === undefined) return undefined;
+  const entries: [string, OpenApi.IExample][] = Object.entries(examples)
+    .map(([name, example]): [string, OpenApi.IExample] => [
+      name,
+      { ...example, value: memberOf(example.value, key) },
+    ])
+    .filter(([, example]) => example.value !== undefined);
+  return entries.length !== 0 ? Object.fromEntries(entries) : undefined;
+};
+
 const warning = new VariadicSingleton((described: boolean): string => {
   const summary = "Request body must be encrypted.";
   const component =