@nestia/sdk 13.0.4 → 14.0.1

package/src/generates/internal/SwaggerOperationComposer.ts

@@ -22,7 +22,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 +33,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 +54,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 +80,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 +88,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 +103,7 @@ export namespace SwaggerOperationComposer {
         .flat(),
       requestBody: writeRequestBody(props),
       responses: SwaggerOperationResponseComposer.compose({
+        config: props.config,
         schema: props.schema,
         route: props.route,
       }),
@@ -108,6 +111,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 +145,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 +156,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,7 +7,9 @@ import { INestiaConfig } from "../../INestiaConfig";
 import {
   JsonSchemasProgrammer,
   MetadataObjectType,
+  MetadataProperty,
   isRequiredOf,
+  isSoleLiteralOf,
 } from "../../internal/legacy";
 import { ITypedHttpRouteParameter } from "../../structures/ITypedHttpRouteParameter";
 import { SwaggerDescriptionComposer } from "./SwaggerDescriptionComposer";
@@ -33,8 +36,8 @@ export namespace SwaggerOperationParameterComposer {
           : header({ ...props, parameter: props.parameter });
 
   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 +45,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 +59,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 +168,76 @@ 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;
+      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;
         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,
-          );
-        }
+        // Only what the document lacks: the parameter's own schema already
+        // brought every component its properties reach, emended for readonly
+        // arrays, and this copy is not.
+        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 +246,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 =

package/src/generates/internal/SwaggerOperationResponseComposer.ts

@@ -1,6 +1,7 @@
 import { OpenApi } from "@typia/interface";
 import { VariadicSingleton } from "tstl";
 
+import { INestiaConfig } from "../../INestiaConfig";
 import { MetadataSchema } from "../../internal/legacy";
 import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
 import { StringUtil } from "../../utils/StringUtil";
@@ -8,9 +9,17 @@ import { SwaggerDescriptionComposer } from "./SwaggerDescriptionComposer";
 
 export namespace SwaggerOperationResponseComposer {
   export const compose = (props: {
+    config: Omit<INestiaConfig.ISwaggerConfig, "output">;
     schema: (metadata: MetadataSchema) => OpenApi.IJsonSchema | undefined;
     route: ITypedHttpRoute;
   }): Record<string, OpenApi.IOperation.IResponse> => {
+    // Swagger 2.0 keys a response's examples by MIME type, one each, so it has
+    // no named examples; the downgrader refuses the whole document rather than
+    // lose them (#1649). The single example still fits.
+    const named = (
+      examples: Record<string, OpenApi.IExample> | undefined,
+    ): Record<string, OpenApi.IExample> | undefined =>
+      props.config.openapi === "2.0" ? undefined : examples;
     const output: Record<string, OpenApi.IOperation.IResponse> = {};
     // FROM DECORATOR
     for (const [status, error] of Object.entries(props.route.exceptions))
@@ -20,7 +29,7 @@ export namespace SwaggerOperationResponseComposer {
           contentType: "application/json",
           schema: props.schema(error.metadata),
           example: error.example,
-          examples: error.examples,
+          examples: named(error.examples),
         }),
       };
 
@@ -32,8 +41,8 @@ export namespace SwaggerOperationResponseComposer {
       )?.text;
       if (text === undefined) continue;
 
-      const elements: string[] = text.split(" ").map((str) => str.trim());
-      const status: string = elements[0]!;
+      // the status is the first word; a tag's text may run over lines
+      const status: string = text.trim().split(/\s+/)[0]!;
       if (
         isNaN(Number(status)) &&
         status !== "2XX" &&
@@ -43,8 +52,8 @@ export namespace SwaggerOperationResponseComposer {
       )
         continue;
 
-      const description: string | undefined =
-        elements.length === 1 ? undefined : elements.slice(1).join(" ");
+      const rest: string = text.trim().substring(status.length).trim();
+      const description: string | undefined = rest.length ? rest : undefined;
       const oldbie = output[status];
       if (description && oldbie !== undefined)
         oldbie.description ??= description;
@@ -75,10 +84,11 @@ export namespace SwaggerOperationResponseComposer {
         jsDocTags: props.route.jsDocTags,
         tag: "return",
       });
-    output[
+    const status: string = String(
       props.route.success.status ??
-        (props.route.method.toLowerCase() === "post" ? 201 : 200)
-    ] = {
+        (props.route.method.toLowerCase() === "post" ? 201 : 200),
+    );
+    output[status] = {
       description: props.route.success.encrypted
         ? `${warning.get(!!description, props.route.method)}${description ?? ""}`
         : (description ?? ""),
@@ -91,12 +101,46 @@ export namespace SwaggerOperationResponseComposer {
             }
           : props.schema(props.route.success.metadata),
         example: props.route.success.example,
-        examples: props.route.success.examples,
+        examples: named(props.route.success.examples),
       }),
-      ...(props.route.success.encrypted ? { "x-nestia-encrypted": true } : {}),
+      // Swagger 2.0 has no place for the flag, and the downgrader refuses the
+      // whole document rather than lose it; the description keeps the warning.
+      ...(props.route.success.encrypted && props.config.openapi !== "2.0"
+        ? { "x-nestia-encrypted": true }
+        : {}),
     };
+    if (props.config.openapi === "2.0") swaggerV2Produces(output, status);
     return output;
   };
+
+  /**
+   * Makes every response body of a Swagger 2.0 operation share one media type.
+   *
+   * 2.0 declares the media types an operation `produces` once for all of its
+   * responses, and the downgrader refuses an operation whose responses disagree
+   * rather than list a type a response does not use (#1649). A route whose
+   * success body is not JSON, such as an encrypted or a query-string one, still
+   * documents its exceptions as JSON, so where the success body has another
+   * type, the exceptions keep their status and description without a body.
+   */
+  const swaggerV2Produces = (
+    output: Record<string, OpenApi.IOperation.IResponse>,
+    success: string,
+  ): void => {
+    const kept: string | undefined = mediaOf(output[success]!);
+    if (kept === undefined) return;
+    for (const [status, response] of Object.entries(output))
+      if (status !== success && mediaOf(response) !== kept)
+        delete response.content;
+  };
+
+  /** The media types of a response body, or `undefined` without one. */
+  const mediaOf = (
+    response: OpenApi.IOperation.IResponse,
+  ): string | undefined =>
+    response.content === undefined
+      ? undefined
+      : Object.keys(response.content).sort().join(" ");
 }
 
 /**
@@ -126,7 +170,7 @@ const composeContent = (props: {
   contentType: string | null | undefined;
   schema: OpenApi.IJsonSchema | undefined;
   example: any;
-  examples: Record<string, any> | undefined;
+  examples: Record<string, OpenApi.IExample> | undefined;
 }): OpenApi.IOperation.IContent | undefined => {
   if (!props.contentType) return undefined;
   const described: boolean =