diff --git a/src/__snapshots__/basic.test.ts.snap b/src/__snapshots__/basic.test.ts.snap index 693fb62..601330a 100644 --- a/src/__snapshots__/basic.test.ts.snap +++ b/src/__snapshots__/basic.test.ts.snap @@ -56,8 +56,6 @@ Base 200 response #||| **Name** -| - **Type** | **Description** || @@ -65,18 +63,18 @@ Base 200 response || type | - string -| - + **Type:** string + + || || foo | - string -| - + **Type:** string + + |||# @@ -110,8 +108,6 @@ Base 200 response #||| **Name** -| - **Type** | **Description** || @@ -119,18 +115,18 @@ Base 200 response || type | - string -| - + **Type:** string + + || || bar | - string -| - + **Type:** string + + |||# diff --git a/src/__snapshots__/combiners/allOf.test.ts.snap b/src/__snapshots__/combiners/allOf.test.ts.snap index 155c952..43ee2b2 100644 --- a/src/__snapshots__/combiners/allOf.test.ts.snap +++ b/src/__snapshots__/combiners/allOf.test.ts.snap @@ -49,8 +49,6 @@ Generated server url #||| **Name** -| - **Type** | **Description** || @@ -58,27 +56,27 @@ Generated server url || type | - string -| - + **Type:** string + + || || foo | - string -| - + **Type:** string + + || || name | - string -| - + **Type:** string + + |||# @@ -112,8 +110,6 @@ Base 200 response #||| **Name** -| - **Type** | **Description** || @@ -121,26 +117,26 @@ Base 200 response || name | - string -| - Default: \`a\` + **Type:** string + +Default: \`a\` || || type | - string -| - + **Type:** string + + || || baz | - string -| - + **Type:** string + + |||# @@ -202,8 +198,6 @@ Generated server url #||| **Name** -| - **Type** | **Description** || @@ -211,9 +205,9 @@ Generated server url || pet | - [Cat](#cat) -| - Cat class + **Type:** [Cat](#cat) + +Cat class |||# @@ -227,8 +221,6 @@ Cat class #||| **Name** -| - **Type** | **Description** || @@ -236,18 +228,18 @@ Cat class || type | - string -| - + **Type:** string + + || || foo | - string -| - + **Type:** string + + |||# @@ -283,8 +275,6 @@ Base 200 response #||| **Name** -| - **Type** | **Description** || @@ -292,9 +282,9 @@ Base 200 response || pet | - [Cat](#cat) -| - Cat class + **Type:** [Cat](#cat) + +Cat class |||# diff --git a/src/__snapshots__/combiners/complex.test.ts.snap b/src/__snapshots__/combiners/complex.test.ts.snap index 0709941..c6d9017 100644 --- a/src/__snapshots__/combiners/complex.test.ts.snap +++ b/src/__snapshots__/combiners/complex.test.ts.snap @@ -52,8 +52,6 @@ Generated server url #||| **Name** -| - **Type** | **Description** || @@ -61,34 +59,34 @@ Generated server url || name | - string -| - Default: \`b\` + **Type:** string + +Default: \`b\` || || age | - any -| - + **Type:** any + + || || - oneOf -| - [Dog](#dog) + ...rest | - Dog class + **oneOf** [Dog](#dog) + +Dog class || || - oneOf -| - [Cat](#cat) + ...rest | - Cat class + **oneOf** [Cat](#cat) + +Cat class |||# @@ -101,8 +99,6 @@ Dog class #||| **Name** -| - **Type** | **Description** || @@ -110,18 +106,18 @@ Dog class || type | - string -| - + **Type:** string + + || || bar | - string -| - + **Type:** string + + |||# @@ -135,8 +131,6 @@ Cat class #||| **Name** -| - **Type** | **Description** || @@ -144,18 +138,18 @@ Cat class || type | - string -| - + **Type:** string + + || || foo | - string -| - + **Type:** string + + |||# @@ -193,8 +187,6 @@ Base 200 response #||| **Name** -| - **Type** | **Description** || @@ -202,34 +194,34 @@ Base 200 response || name | - string -| - Default: \`b\` + **Type:** string + +Default: \`b\` || || age | - any -| - + **Type:** any + + || || - oneOf -| - [Dog](#dog) + ...rest | - Dog class + **oneOf** [Dog](#dog) + +Dog class || || - oneOf + ...rest | - [Cat](#cat) -| - Cat class + **oneOf** [Cat](#cat) + +Cat class |||# diff --git a/src/__snapshots__/combiners/oneOf.test.ts.snap b/src/__snapshots__/combiners/oneOf.test.ts.snap index 9fdefa5..292ceca 100644 --- a/src/__snapshots__/combiners/oneOf.test.ts.snap +++ b/src/__snapshots__/combiners/oneOf.test.ts.snap @@ -48,26 +48,24 @@ Generated server url #||| **Name** -| - **Type** | **Description** || || - oneOf -| - [Dog](#dog) + ...rest | - Dog class + **oneOf** [Dog](#dog) + +Dog class || || - oneOf -| - [Cat](#cat) + ...rest | - Cat class + **oneOf** [Cat](#cat) + +Cat class |||# @@ -80,8 +78,6 @@ Dog class #||| **Name** -| - **Type** | **Description** || @@ -89,18 +85,18 @@ Dog class || type | - string -| - + **Type:** string + + || || baz | - string -| - + **Type:** string + + |||# @@ -114,8 +110,6 @@ Cat class #||| **Name** -| - **Type** | **Description** || @@ -123,18 +117,18 @@ Cat class || type | - string -| - + **Type:** string + + || || foo | - string -| - + **Type:** string + + |||# @@ -166,26 +160,24 @@ Cat class #||| **Name** -| - **Type** | **Description** || || - oneOf + ...rest | - [Dog](#dog) -| - Dog class + **oneOf** [Dog](#dog) + +Dog class || || - oneOf -| - [Cat](#cat) + ...rest | - Cat class + **oneOf** [Cat](#cat) + +Cat class |||# @@ -246,8 +238,6 @@ Generated server url #||| **Name** -| - **Type** | **Description** || @@ -255,35 +245,35 @@ Generated server url || name | - string -| - + **Type:** string + + || || age | - number -| - + **Type:** number + + || || - oneOf -| - [Dog](#dog) + ...rest | - Dog class + **oneOf** [Dog](#dog) + +Dog class || || - oneOf -| - [Cat](#cat) + ...rest | - Cat class + **oneOf** [Cat](#cat) + +Cat class |||# @@ -296,8 +286,6 @@ Dog class #||| **Name** -| - **Type** | **Description** || @@ -305,18 +293,18 @@ Dog class || type | - string -| - + **Type:** string + + || || baz | - string -| - + **Type:** string + + |||# @@ -330,8 +318,6 @@ Cat class #||| **Name** -| - **Type** | **Description** || @@ -339,18 +325,18 @@ Cat class || type | - string -| - + **Type:** string + + || || foo | - string -| - + **Type:** string + + |||# @@ -384,8 +370,6 @@ Cat class #||| **Name** -| - **Type** | **Description** || @@ -393,35 +377,35 @@ Cat class || name | - string -| - + **Type:** string + + || || age | - number -| - + **Type:** number + + || || - oneOf + ...rest | - [Dog](#dog) -| - Dog class + **oneOf** [Dog](#dog) + +Dog class || || - oneOf + ...rest | - [Cat](#cat) -| - Cat class + **oneOf** [Cat](#cat) + +Cat class |||# @@ -484,8 +468,6 @@ Generated server url #||| **Name** -| - **Type** | **Description** || @@ -493,27 +475,27 @@ Generated server url || pet | - [Dog](#dog) -or [Cat](#cat) -| - + **Type:** [Dog](#dog) +or [Cat](#cat) + + || || - oneOf -| - [Dog](#dog) + ...rest | - Dog class + **oneOf** [Dog](#dog) + +Dog class || || - oneOf -| - [Cat](#cat) + ...rest | - Cat class + **oneOf** [Cat](#cat) + +Cat class |||# @@ -526,8 +508,6 @@ Dog class #||| **Name** -| - **Type** | **Description** || @@ -535,18 +515,18 @@ Dog class || type | - string -| - + **Type:** string + + || || baz | - string -| - + **Type:** string + + |||# @@ -560,8 +540,6 @@ Cat class #||| **Name** -| - **Type** | **Description** || @@ -569,18 +547,18 @@ Cat class || type | - string -| - + **Type:** string + + || || foo | - string -| - + **Type:** string + + |||# @@ -616,8 +594,6 @@ Cat class #||| **Name** -| - **Type** | **Description** || @@ -625,27 +601,27 @@ Cat class || pet | - [Dog](#dog) -or [Cat](#cat) -| - + **Type:** [Dog](#dog) +or [Cat](#cat) + + || || - oneOf -| - [Dog](#dog) + ...rest | - Dog class + **oneOf** [Dog](#dog) + +Dog class || || - oneOf -| - [Cat](#cat) + ...rest | - Cat class + **oneOf** [Cat](#cat) + +Cat class |||# diff --git a/src/__snapshots__/description.test.ts.snap b/src/__snapshots__/description.test.ts.snap index 96b5ed6..1790d29 100644 --- a/src/__snapshots__/description.test.ts.snap +++ b/src/__snapshots__/description.test.ts.snap @@ -65,8 +65,6 @@ Generated server url #||| **Name** -| - **Type** | **Description** || @@ -74,36 +72,36 @@ Generated server url || pet | - [Cat](#cat) -| - From response + **Type:** [Cat](#cat) + +From response || || petWithoutDescription | - [Cat](#cat) -| - Cat class + **Type:** [Cat](#cat) + +Cat class || || refToSchemaWithDescription | - [Dog](#dog) -| - Dog class + **Type:** [Dog](#dog) + +Dog class || || simpleDescription | - object -| - Simple description + **Type:** object + +Simple description |||# @@ -117,8 +115,6 @@ Cat class #||| **Name** -| - **Type** | **Description** || @@ -126,18 +122,18 @@ Cat class || type | - string -| - + **Type:** string + + || || foo | - string -| - + **Type:** string + + |||# @@ -151,8 +147,6 @@ Dog class #||| **Name** -| - **Type** | **Description** || @@ -160,18 +154,18 @@ Dog class || type | - string -| - + **Type:** string + + || || bar | - string -| - + **Type:** string + + |||# diff --git a/src/__snapshots__/examples/array.test.ts.snap b/src/__snapshots__/examples/array.test.ts.snap index 00263f6..19da5f1 100644 --- a/src/__snapshots__/examples/array.test.ts.snap +++ b/src/__snapshots__/examples/array.test.ts.snap @@ -52,8 +52,6 @@ Generated server url #||| **Name** -| - **Type** | **Description** || @@ -61,9 +59,10 @@ Generated server url || a | - object[] -| - + **Type:** object[] + + + |||# @@ -154,8 +153,6 @@ Generated server url #||| **Name** -| - **Type** | **Description** || @@ -163,9 +160,10 @@ Generated server url || a | - any[] -| - + **Type:** any[] + + + |||# @@ -252,8 +250,6 @@ Generated server url #||| **Name** -| - **Type** | **Description** || @@ -261,10 +257,11 @@ Generated server url || a | - (string -or integer)[] -| - + **Type:** (string +or integer)[] + + + |||# @@ -443,8 +440,6 @@ Generated server url #||| **Name** -| - **Type** | **Description** || @@ -452,9 +447,9 @@ Generated server url || name | - string -| - + **Type:** string + + |||# @@ -550,8 +545,6 @@ Generated server url #||| **Name** -| - **Type** | **Description** || @@ -559,9 +552,9 @@ Generated server url || name | - string -| - + **Type:** string + + |||# diff --git a/src/__snapshots__/examples/base.test.ts.snap b/src/__snapshots__/examples/base.test.ts.snap index e407e5e..7055f34 100644 --- a/src/__snapshots__/examples/base.test.ts.snap +++ b/src/__snapshots__/examples/base.test.ts.snap @@ -125,8 +125,6 @@ Generated server url #||| **Name** -| - **Type** | **Description** || @@ -134,9 +132,9 @@ Generated server url || name | - string -| - + **Type:** string + + |||# @@ -220,18 +218,14 @@ Generated server url #||| **Name** -| - **Type** | **Description** || || - oneOf + ...rest | - [Cat](#cat) -| - + **oneOf** [Cat](#cat) |||# @@ -242,8 +236,6 @@ Generated server url #||| **Name** -| - **Type** | **Description** || @@ -251,9 +243,9 @@ Generated server url || name | - string -| - + **Type:** string + + |||# diff --git a/src/__snapshots__/length.test.ts.snap b/src/__snapshots__/length.test.ts.snap index c1bc0e4..06d5045 100644 --- a/src/__snapshots__/length.test.ts.snap +++ b/src/__snapshots__/length.test.ts.snap @@ -64,8 +64,6 @@ Generated server url #||| **Name** -| - **Type** | **Description** || @@ -73,27 +71,27 @@ Generated server url || pet | - [Cat](#cat) -| - From response + **Type:** [Cat](#cat) + +From response || || petWithoutDescription | - [Cat](#cat) -| - Cat class + **Type:** [Cat](#cat) + +Cat class || || refToSchemaWithDescription | - [Dog](#dog) -| - Dog class + **Type:** [Dog](#dog) + +Dog class |||# @@ -107,8 +105,6 @@ Cat class #||| **Name** -| - **Type** | **Description** || @@ -116,18 +112,18 @@ Cat class || name | - string -| - + **Type:** string + + || || foo | - string -| - Min length: \`3\` + **Type:** string + +Min length: \`3\` |||# @@ -140,8 +136,6 @@ Dog class #||| **Name** -| - **Type** | **Description** || @@ -149,18 +143,18 @@ Dog class || name | - string -| - Pet name -
Max length: \`100\` + **Type:** string + +Pet name +
Max length: \`100\` || || bar | - string -| - Min length: \`1\`
Max length: \`99\` + **Type:** string + +Min length: \`1\`
Max length: \`99\` |||# diff --git a/src/__snapshots__/required.test.ts.snap b/src/__snapshots__/required.test.ts.snap index a064426..130f1e7 100644 --- a/src/__snapshots__/required.test.ts.snap +++ b/src/__snapshots__/required.test.ts.snap @@ -48,8 +48,6 @@ Generated server url #||| **Name** -| - **Type** | **Description** || @@ -57,45 +55,45 @@ Generated server url || a* | - number -| - + **Type:** number + + || || b* | - number -| - + **Type:** number + + || || c | - number -| - + **Type:** number + + || || d* | - number -| - + **Type:** number + + || || e | - number -| - + **Type:** number + + |||# @@ -129,8 +127,6 @@ Cat class #||| **Name** -| - **Type** | **Description** || @@ -138,18 +134,18 @@ Cat class || type | - string -| - + **Type:** string + + || || foo | - string -| - + **Type:** string + + |||# diff --git a/src/includer/traverse/description.ts b/src/includer/traverse/description.ts new file mode 100644 index 0000000..c7653c1 --- /dev/null +++ b/src/includer/traverse/description.ts @@ -0,0 +1,119 @@ +import {EOL} from '../constants'; +import {OpenJSONSchema} from '../models'; +import {concatNewLine} from '../utils'; + +type Field = { + key: keyof OpenJSONSchema; + label: string; + computed?: unknown; + notWrapValueIntoCode?: boolean; +}; + +type Fields = (Field | ((value: OpenJSONSchema) => Field | undefined))[]; + +/* @todo add i18n */ +const fields: Fields = [ + { + key: 'default', + label: 'Default', + }, + { + key: 'example', + label: 'Example', + }, + { + key: 'minLength', + label: 'Min length', + }, + { + key: 'maxLength', + label: 'Max length', + }, + { + key: 'maxItems', + label: 'Max items', + }, + { + key: 'minItems', + label: 'Min items', + }, + { + key: 'pattern', + label: 'Pattern', + }, + { + key: 'uniqueItems', + label: 'Unique items', + }, + (value) => { + return { + key: 'minimum', + label: `Min value${value.exclusiveMinimum ? ' (exclusive)' : ''}`, + }; + }, + (value) => { + return { + key: 'maximum', + label: `Max value${value.exclusiveMaximum ? ' (exclusive)' : ''}`, + }; + }, + (value: OpenJSONSchema) => { + const enumValues = value.enum?.map((s) => `\`${s}\``).join(', '); + + if (!enumValues) { + return undefined; + } + + return { + computed: enumValues as Field['key'], + notWrapValueIntoCode: true, + key: 'enum', + label: 'Enum', + }; + }, +]; + +function prepareComplexDescription(baseDescription: string, value: OpenJSONSchema): string { + const description = baseDescription + EOL; + + return fields.reduce((acc, curr) => { + const field = typeof curr === 'function' ? curr(value) : curr; + + if (typeof field === 'undefined' || !value[field.key]) { + return acc; + } + + const {key, label, computed, notWrapValueIntoCode} = field; + + return concatConstraint(acc, computed || value[key], label + ':', notWrapValueIntoCode); + }, description); +} + +function concatConstraint( + description: string, + constraint: unknown, + constraintLabel: string, + notWrapValueIntoCode = false, +) { + if (typeof constraint !== 'undefined') { + return concatNewLine( + description, + `${constraintLabel} ${prepareConstraintValue( + constraint, + notWrapValueIntoCode, + )}`, + ); + } + + return description; +} + +function prepareConstraintValue(value: unknown, notWrapValueIntoCode: boolean) { + if (typeof value === 'boolean') { + return ''; + } + return notWrapValueIntoCode ? value : `\`${value}\``; +} + +export {fields, prepareComplexDescription}; +export default {fields, prepareComplexDescription}; diff --git a/src/includer/traverse/tables.ts b/src/includer/traverse/tables.ts index c4d67d5..6657287 100644 --- a/src/includer/traverse/tables.ts +++ b/src/includer/traverse/tables.ts @@ -1,13 +1,13 @@ import RefsService from '../services/refs'; import stringify from 'json-stringify-safe'; -import {anchor, table, tableParameterName} from '../ui'; +import {anchor, block, bold, table, tableParameterName} from '../ui'; import {concatNewLine} from '../utils'; -import {EOL} from '../constants'; import {OpenJSONSchema, OpenJSONSchemaDefinition} from '../models'; import {collectRefs, extractOneOfElements, inferType, typeToText} from './types'; +import {prepareComplexDescription} from './description'; -type TableRow = [string, string, string]; +type TableRow = [string, string]; export type TableRef = string; @@ -40,7 +40,7 @@ export function tableFromSchema(schema: OpenJSONSchema): TableFromSchemaResult { } const {rows, refs} = prepareObjectSchemaTable(schema); - const content = rows.length ? table([['Name', 'Type', 'Description'], ...rows]) : ''; + const content = rows.length ? table([['Name', 'Description'], ...rows]) : ''; return {content, tableRefs: refs}; } @@ -61,7 +61,7 @@ function prepareObjectSchemaTable(schema: OpenJSONSchema): PrepareObjectSchemaTa const name = tableParameterName(key, isRequired(key, merged)); const {type, description, ref, runtimeRef} = prepareTableRowData(value, key, tableRef); - result.rows.push([name, type, description]); + result.rows.push([name, block([`${bold('Type:')} ${type}`, description])]); if (ref) { result.refs.push(...ref); @@ -99,7 +99,10 @@ function prepareObjectSchemaTable(schema: OpenJSONSchema): PrepareObjectSchemaTa return; } - result.rows.push(['oneOf', anchor(ref), value.description || '']); + result.rows.push([ + '...rest', + block([`${bold('oneOf')} ${anchor(ref)}`, value.description || '']), + ]); result.refs.push(ref); }); @@ -145,7 +148,7 @@ export function prepareTableRowData( return { type: `${anchor(inner.runtimeRef, key)}[]`, runtimeRef: inner.runtimeRef, - description: innerDescription, + description: prepareComplexDescription(innerDescription, value), }; } @@ -156,7 +159,7 @@ export function prepareTableRowData( type: returnType, // if inner.ref present, inner description will be in separate table ref: inner.ref, - description: innerDescription, + description: prepareComplexDescription(innerDescription, value), }; } @@ -179,49 +182,6 @@ export function prepareTableRowData( }; } -function prepareComplexDescription(baseDescription: string, value: OpenJSONSchema): string { - let description = baseDescription + EOL; - - const enumValues = value.enum?.map((s) => `\`${s}\``).join(', '); - - if (typeof enumValues !== 'undefined') { - description = concatNewLine( - description, - `Enum: ${enumValues}`, - ); - } - - if (typeof value.default !== 'undefined') { - description = concatNewLine( - description, - `Default: \`${value.default}\``, - ); - } - - if (typeof value.example !== 'undefined') { - description = concatNewLine( - description, - `Example: \`${value.example}\``, - ); - } - - if (typeof value.minLength !== 'undefined') { - description = concatNewLine( - description, - `Min length: \`${value.minLength}\``, - ); - } - - if (typeof value.maxLength !== 'undefined') { - description = concatNewLine( - description, - `Max length: \`${value.maxLength}\``, - ); - } - - return description; -} - function findNonNullOneOfElement(schema: OpenJSONSchema): OpenJSONSchema { const isValid = (v: OpenJSONSchema) => { if (typeof inferType(v) === 'string') { @@ -312,6 +272,7 @@ export function prepareSampleObject( return result; } +// eslint-disable-next-line function prepareSampleElement( key: string, v: OpenJSONSchemaDefinition, diff --git a/src/includer/ui/endpoint.ts b/src/includer/ui/endpoint.ts index 15d9b85..823e316 100644 --- a/src/includer/ui/endpoint.ts +++ b/src/includer/ui/endpoint.ts @@ -182,7 +182,7 @@ function parameters(pagePrintedRefs: Set, params?: Parameters) { } } tables.push(title(3)(heading)); - tables.push(table([['Name', 'Type', 'Description'], ...rows])); + tables.push(table([['Name', 'Description'], ...rows])); tables.push(...printAllTables(pagePrintedRefs, tableRefs)); } } @@ -203,7 +203,10 @@ function parameterRow(param: Parameter): {cells: string[]; ref?: TableRef[]} { description = concatNewLine(description, `Default: \`${param.default}\``); } return { - cells: [tableParameterName(param.name, param.required), row.type, description], + cells: [ + tableParameterName(param.name, param.required), + block([`${bold('Type:')} ${row.type}`, description]), + ], ref: row.ref, }; } diff --git a/src/runtime/index.scss b/src/runtime/index.scss index 07f492f..9c50786 100644 --- a/src/runtime/index.scss +++ b/src/runtime/index.scss @@ -11,6 +11,10 @@ --dc-openapi-status-code-server: rgb(255, 190, 92); --dc-openapi-highlight: rgb(233, 174, 86); + + .openapi-description-annotation { + color: gray; + } &__required { color: var(--g-color-text-danger);