@scalar/openapi-to-markdown 1.5.3 → 1.6.0

package/dist/render-operation.js

@@ -21,22 +21,27 @@ const contentType = (mediaType) => paragraph(strong(text('Content type:')), text
  * return the same error schema, share one key. Anything else a response declares keeps it separate.
  */
 const getResponseKey = (response, ids) => {
-    if (Object.keys(response.headers ?? {}).length || Object.keys(response.links ?? {}).length)
+    if (Object.keys(response.headers ?? {}).length || Object.keys(response.links ?? {}).length) {
         return undefined;
+    }
     const content = Object.entries(response.content ?? {});
-    if (!content.length)
+    if (!content.length) {
         return undefined;
+    }
     const parts = [];
     for (const [mediaType, media] of content) {
         const schema = getResolvedRef(media.schema);
-        if (!isObject(schema) || media.example !== undefined || media.examples || media.encoding)
+        if (!isObject(schema) || media.example !== undefined || media.examples || media.encoding) {
             return undefined;
-        if (!ids.has(schema))
+        }
+        if (!ids.has(schema)) {
             ids.set(schema, ids.size);
+        }
         // Reference siblings change the schema, so only a plain reference shares its target's identity.
         const siblings = isObject(media.schema) ? Object.keys(media.schema).filter((key) => !key.startsWith('$')) : [];
-        if (siblings.length)
+        if (siblings.length) {
             return undefined;
+        }
         parts.push(mediaType, ids.get(schema));
     }
     return JSON.stringify(parts);
@@ -49,15 +54,18 @@ export const renderOperation = async (document, path, method, pathItem, operatio
     const displayMethod = formatOperationMethod(method);
     const openapiVersion = document['x-original-oas-version'] ?? document.openapi;
     const stability = operation['x-scalar-stability'];
-    const title = (operation.summary || `${displayMethod} ${path}`) +
-        (stability ? ` (${stability})` : operation.deprecated ? ' ⚠️ Deprecated' : '');
+    const deprecatedLabel = operation.deprecated ? ' ⚠️ Deprecated' : '';
+    const title = (operation.summary || `${displayMethod} ${path}`) + (stability ? ` (${stability})` : deprecatedLabel);
     const metadata = [field('Method', inlineCode(displayMethod)), field(webhook ? 'Webhook' : 'Path', inlineCode(path))];
-    if (operation.operationId)
+    if (operation.operationId) {
         metadata.push(field('Operation ID', inlineCode(operation.operationId)));
-    if (operation.tags)
+    }
+    if (operation.tags) {
         metadata.push(field('Tags', text(operation.tags.join(', '))));
-    if (stability)
+    }
+    if (stability) {
         metadata.push(field('Stability', text(stability)));
+    }
     const nodes = [
         heading(h(0), text(title)),
         list(metadata),
@@ -67,8 +75,9 @@ export const renderOperation = async (document, path, method, pathItem, operatio
     let inheritedServers;
     let serverAnchor;
     if (documentContext && operation.servers === undefined) {
-        if (pathItem.servers === undefined)
+        if (pathItem.servers === undefined) {
             inheritedServers = documentContext.servers;
+        }
         else {
             inheritedServers = documentContext.pathServers.get(pathItem);
             if (inheritedServers === undefined) {
@@ -81,8 +90,9 @@ export const renderOperation = async (document, path, method, pathItem, operatio
         nodes.push(paragraph(strong(text('Servers:')), text(' '), link(`#${inheritedServers}`, 'Inherited servers')));
     }
     else if (servers !== undefined) {
-        if (serverAnchor)
+        if (serverAnchor) {
             nodes.push(anchor(serverAnchor));
+        }
         nodes.push(heading(h(1), text('Effective servers')));
         const serverItems = [];
         // An explicit empty server array overrides inherited servers with the OAS default `/`.
@@ -93,23 +103,27 @@ export const renderOperation = async (document, path, method, pathItem, operatio
                 ...(await description(server.description)),
             ];
             const variables = Object.entries(server.variables ?? {});
-            if (variables.length)
+            if (variables.length) {
                 blocks.push(list(await Promise.all(variables.map(async ([name, variable]) => item(paragraph(text(`${name}: `), inlineCode(variable.default), ...(variable.enum?.length
                     ? [text(', possible values: '), inlineCode(variable.enum.join(', '))]
                     : [])), ...(await description(variable.description)))))));
+            }
             serverItems.push(item(...blocks));
         }
         nodes.push(list(serverItems));
     }
-    if (documentContext?.authentication && operation.security === undefined)
+    if (documentContext?.authentication && operation.security === undefined) {
         nodes.push(paragraph(strong(text('Authentication:')), text(' '), link(`#${documentContext.authentication}`, 'Global authentication')));
-    else
+    }
+    else {
         nodes.push(...(await renderSecurity(operation.security ?? document.security, document.components?.securitySchemes, description, h(1))));
+    }
     const parameters = new Map();
     for (const reference of [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])]) {
         const parameter = getResolvedRef(reference, mergeSiblingReferences);
-        if (parameter)
+        if (parameter) {
             parameters.set(`${parameter.in}:${parameter.name}`, parameter);
+        }
     }
     const locations = [
         ...parameterLocations,
@@ -120,22 +134,26 @@ export const renderOperation = async (document, path, method, pathItem, operatio
     for (const [location, sectionTitle] of locations) {
         const entries = [];
         for (const parameter of parameters.values()) {
-            if (parameter.in !== location)
+            if (parameter.in !== location) {
                 continue;
+            }
             entries.push(await renderParameter(parameter, { description, schemas, examples, openapiVersion, document }));
         }
-        if (entries.length)
+        if (entries.length) {
             nodes.push(heading(h(1), text(sectionTitle)), list(entries));
+        }
     }
     const body = getResolvedRef(operation.requestBody, mergeSiblingReferences);
     if (body) {
         nodes.push(heading(h(1), text('Request body')), ...(await description(body.description)));
-        if (typeof body.required === 'boolean')
+        if (typeof body.required === 'boolean') {
             nodes.push(paragraph(strong(text('Required:')), text(' '), inlineCode(body.required)));
+        }
         for (const [mediaType, content] of Object.entries(body.content ?? {})) {
             nodes.push(contentType(mediaType));
-            if (content.schema !== undefined)
+            if (content.schema !== undefined) {
                 nodes.push(...schemas.render(content.schema));
+            }
             nodes.push(...(await renderExamples(content, description, mediaType, 'write', openapiVersion, document.openapi, {
                 linked: schemas.linked,
                 examples,
@@ -154,8 +172,9 @@ export const renderOperation = async (document, path, method, pathItem, operatio
         const key = getResponseKey(entry.response, ids) ?? `status:${entry.status}`;
         groups.set(key, [...(groups.get(key) ?? []), entry]);
     }
-    if (responses.length)
+    if (responses.length) {
         nodes.push(heading(h(1), text('Responses')));
+    }
     for (const group of groups.values()) {
         const { response } = group[0];
         if (group.length > 1) {
@@ -168,8 +187,9 @@ export const renderOperation = async (document, path, method, pathItem, operatio
         nodes.push(...(await renderHeaders(response.headers, description, schemas, openapiVersion, document.openapi, examples)), ...(await renderResponseLinks(response.links, description)));
         for (const [mediaType, content] of Object.entries(response.content ?? {})) {
             nodes.push(contentType(mediaType));
-            if (content.schema !== undefined)
+            if (content.schema !== undefined) {
                 nodes.push(...schemas.render(content.schema));
+            }
             nodes.push(...(await renderExamples(content, description, mediaType, 'read', openapiVersion, document.openapi, {
                 linked: schemas.linked,
                 examples,
@@ -187,19 +207,25 @@ const renderParameter = async (parameter, { description, schemas, examples, open
     const schema = 'schema' in parameter ? parameter.schema : undefined;
     const summary = schema === undefined ? [] : schemas.summarize(schema);
     const add = (label, value) => {
-        if (value !== undefined)
+        if (value !== undefined) {
             summary.push(text(`${summary.length ? ', ' : ''}${label}: `), inlineCode(value));
+        }
     };
-    if ('style' in parameter)
+    if ('style' in parameter) {
         add('style', parameter.style);
-    if ('explode' in parameter && typeof parameter.explode === 'boolean')
+    }
+    if ('explode' in parameter && typeof parameter.explode === 'boolean') {
         add('explode', parameter.explode);
-    if (parameter.allowEmptyValue)
+    }
+    if (parameter.allowEmptyValue) {
         add('allowEmptyValue', true);
-    if ('allowReserved' in parameter && parameter.allowReserved)
+    }
+    if ('allowReserved' in parameter && parameter.allowReserved) {
         add('allowReserved', true);
-    if (summary.length)
+    }
+    if (summary.length) {
         title.push(text(': '), ...summary);
+    }
     const blocks = [
         paragraph(...title),
         ...(await description(parameter.description)),
@@ -207,16 +233,19 @@ const renderParameter = async (parameter, { description, schemas, examples, open
     if (schema !== undefined) {
         // The schema's own description usually repeats the parameter's, so print it only when it differs.
         const schemaDescription = schemas.view(schema).description;
-        if (schemaDescription?.trim() !== parameter.description?.trim())
+        if (schemaDescription?.trim() !== parameter.description?.trim()) {
             blocks.push(...describe(schemaDescription));
+        }
         blocks.push(...schemas.render(schema, 0, [], { hideDetails: true }));
     }
-    if ('example' in parameter || 'examples' in parameter)
+    if ('example' in parameter || 'examples' in parameter) {
         blocks.push(...(await renderExamples({ example: parameter.example, examples: parameter.examples }, description, 'application/json', 'write', openapiVersion, document.openapi, { examples })));
+    }
     for (const [mediaType, content] of Object.entries('content' in parameter ? (parameter.content ?? {}) : {})) {
         blocks.push(contentType(mediaType));
-        if (content.schema !== undefined)
+        if (content.schema !== undefined) {
             blocks.push(...schemas.render(content.schema));
+        }
         blocks.push(...(await renderExamples(content, description, mediaType, 'write', openapiVersion, document.openapi, {
             linked: schemas.linked,
             examples,

package/dist/render-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-schema.d.ts","sourceRoot":"","sources":["../src/render-schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"render-schema.d.ts","sourceRoot":"","sources":["../src/render-schema.ts"],"names":[],"mappings":"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"}