-
-# description
-
-## Request
-
-#||| **method** | **url** | **description** ||
-
-||
-\`\`\`
-POST
-\`\`\`
- |
-\`\`\`
-http://localhost:8080/test
-\`\`\`
- |
-\`\`\`
-Generated server url
-\`\`\`
- |||#
-
-## Responses
-
-## 200 OK
-
-#### Body
-
-{% cut "application/json" %}
-
-
-\`\`\`
-{
- "pet": {
- "type": "string",
- "foo": "string"
- },
- "petWithoutDescription": {
- "type": "string",
- "foo": "string"
- },
- "refToSchemaWithDescription": {
- "type": "string",
- "bar": "string"
- },
- "simpleDescription": {}
-}
-\`\`\`
-
-
-{% endcut %}
-
-
-#||| **Name** | **Type** | **Description** ||
-
-|| pet | [Cat](#cat) | From response ||
-
-|| petWithoutDescription | [Cat](#cat) | Cat class ||
-
-|| refToSchemaWithDescription | [Dog](#dog) | Dog class ||
-
-|| simpleDescription | object | Simple description |||#
-
-### Cat
-
-Cat class
-
-#||| **Name** | **Type** | **Description** ||
-
-|| type | string | ||
-
-|| foo | string | |||#
-
-### Dog
-
-Dog class
-
-#||| **Name** | **Type** | **Description** ||
-
-|| type | string | ||
-
-|| bar | string | |||#
-
-
-
"
-`;
diff --git a/src/__snapshots__/length.test.ts.snap b/src/__snapshots__/length.test.ts.snap
index edb7684..46155de 100644
--- a/src/__snapshots__/length.test.ts.snap
+++ b/src/__snapshots__/length.test.ts.snap
@@ -110,20 +110,20 @@ Cat class
||
||
- name
+ foo
|
**Type:** string
-
-
+
### Body
@@ -71,7 +97,7 @@ Generated server url
||
||
- c
+ d
*
|
**Type:** number
@@ -80,7 +106,7 @@ Generated server url
||
||
- d
*
+ c
|
**Type:** number
@@ -132,7 +158,7 @@ Cat class
||
||
- type
+ foo
|
**Type:** string
@@ -141,7 +167,7 @@ Cat class
||
||
- foo
+ type
|
**Type:** string
diff --git a/src/__snapshots__/required/required.test.ts.snap b/src/__snapshots__/required/required.test.ts.snap
deleted file mode 100644
index b1b06f9..0000000
--- a/src/__snapshots__/required/required.test.ts.snap
+++ /dev/null
@@ -1,89 +0,0 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
-
-exports[`description renders correct description 1`] = `
-"
-
-# TEST ENDPOINT
-
-## Request
-
-#||| **method** | **url** | **description** ||
-
-||
-\`\`\`
-POST
-\`\`\`
- |
-\`\`\`
-http://localhost:8080/description
-\`\`\`
- |
-\`\`\`
-Generated server url
-\`\`\`
- |||#
-
-### Query parameters
-
-#||| **Name** | **Type** | **Description** ||
-
-|| a | number | ||
-
-|| b | number | ||
-
-|| c* | number | |||#
-
-#### Body
-
-{% cut "application/json" %}
-
-
-\`\`\`
-{
- "a": 0,
- "b": 0,
- "c": 0
-}
-\`\`\`
-
-
-{% endcut %}
-
-
-#||| **Name** | **Type** | **Description** ||
-
-|| a* | number | ||
-
-|| b | number | ||
-
-|| c | number | |||#
-
-## Responses
-
-## 200 OK
-
-#### Body
-
-{% cut "application/json" %}
-
-
-\`\`\`
-{
- "type": "string",
- "foo": "string"
-}
-\`\`\`
-
-
-{% endcut %}
-
-
-#||| **Name** | **Type** | **Description** ||
-
-|| type | string | ||
-
-|| foo | string | |||#
-
-
-
"
-`;
diff --git a/src/__tests__/__helpers__/run.ts b/src/__tests__/__helpers__/run.ts
index 11ed6ed..ee64aeb 100644
--- a/src/__tests__/__helpers__/run.ts
+++ b/src/__tests__/__helpers__/run.ts
@@ -99,8 +99,8 @@ export class DocumentBuilder {
requestBody: this.requestBody,
operationId: this.id,
responses: Object.fromEntries(this.responses),
+ parameters: this.parameters,
},
- parameters: this.parameters,
},
},
components: {
diff --git a/src/__tests__/objectPropertyOrder.test.ts b/src/__tests__/objectPropertyOrder.test.ts
new file mode 100644
index 0000000..b344cea
--- /dev/null
+++ b/src/__tests__/objectPropertyOrder.test.ts
@@ -0,0 +1,80 @@
+import {DocumentBuilder, run} from './__helpers__/run';
+
+const mockDocumentName = 'ObjectPropertyOrder';
+
+describe('Property rows in tables describing object schemas', () => {
+ it('are ordered lexicographically by default', async () => {
+ const spec = new DocumentBuilder(mockDocumentName)
+ .component('StarDto', {
+ type: 'object',
+ properties: {
+ id: {
+ description: 'Internal ID for this star',
+ type: 'string',
+ format: 'uuid',
+ },
+ luminosityClass: {
+ description: 'Morgan-Keenan luminosity class for this star',
+ type: 'string',
+ },
+ name: {
+ description: 'Name of this star',
+ type: 'string',
+ },
+ catalogueDesignationCCDM: {
+ description: 'CCDM catalogue designation for this star',
+ type: 'string',
+ },
+ },
+ })
+ .request({
+ schema: DocumentBuilder.ref('StarDto'),
+ })
+ .response(204, {})
+ .build();
+
+ const fs = await run(spec);
+
+ const page = fs.match(mockDocumentName);
+
+ expect(page).toMatchSnapshot();
+ });
+
+ it('are hoisted to the top of the table if marked as required by the spec', async () => {
+ const spec = new DocumentBuilder(mockDocumentName)
+ .component('StarDto', {
+ type: 'object',
+ properties: {
+ id: {
+ description: 'Internal ID for this star',
+ type: 'string',
+ format: 'uuid',
+ },
+ luminosityClass: {
+ description: 'Morgan-Keenan luminosity class for this star',
+ type: 'string',
+ },
+ name: {
+ description: 'Name of this star',
+ type: 'string',
+ },
+ catalogueDesignationCCDM: {
+ description: 'CCDM catalogue designation for this star',
+ type: 'string',
+ },
+ },
+ required: ['id', 'name', 'luminosityClass'],
+ })
+ .request({
+ schema: DocumentBuilder.ref('StarDto'),
+ })
+ .response(204, {})
+ .build();
+
+ const fs = await run(spec);
+
+ const page = fs.match(mockDocumentName);
+
+ expect(page).toMatchSnapshot();
+ });
+});
diff --git a/src/__tests__/parameterOrder.test.ts b/src/__tests__/parameterOrder.test.ts
new file mode 100644
index 0000000..3b1617c
--- /dev/null
+++ b/src/__tests__/parameterOrder.test.ts
@@ -0,0 +1,80 @@
+import {DocumentBuilder, run} from './__helpers__/run';
+
+const mockDocumentName = 'ParameterOrder';
+
+describe('Endpoint parameters in tables', () => {
+ it('are ordered lexicographically by default', async () => {
+ const spec = new DocumentBuilder(mockDocumentName)
+ .parameter({
+ in: 'query',
+ name: 'name',
+ description: 'Name for the requested star',
+ schema: {
+ type: 'string',
+ },
+ })
+ .parameter({
+ in: 'query',
+ name: 'id',
+ description: 'Internal ID for the requested star',
+ schema: {
+ type: 'string',
+ format: 'uuid',
+ },
+ })
+ .parameter({
+ in: 'query',
+ name: 'catalogueCCDM',
+ description: 'CCDM designation for the requested star',
+ schema: {
+ type: 'string',
+ },
+ })
+ .response(204, {})
+ .build();
+
+ const fs = await run(spec);
+
+ const page = fs.match(mockDocumentName);
+
+ expect(page).toMatchSnapshot();
+ });
+
+ it('are hoisted to the top of the table if marked as required by the spec', async () => {
+ const spec = new DocumentBuilder(mockDocumentName)
+ .parameter({
+ in: 'query',
+ name: 'name',
+ description: 'Name for the requested star',
+ schema: {
+ type: 'string',
+ },
+ })
+ .parameter({
+ in: 'query',
+ name: 'id',
+ required: true,
+ description: 'Internal ID for the requested star',
+ schema: {
+ type: 'string',
+ format: 'uuid',
+ },
+ })
+ .parameter({
+ in: 'query',
+ name: 'catalogueCCDM',
+ description: 'CCDM designation for the requested star',
+ schema: {
+ type: 'string',
+ },
+ })
+ .response(204, {})
+ .build();
+
+ const fs = await run(spec);
+
+ const page = fs.match(mockDocumentName);
+
+ expect(page).toMatchSnapshot();
+ })
+});
diff --git a/src/includer/traverse/tables.ts b/src/includer/traverse/tables.ts
index 6657287..1823248 100644
--- a/src/includer/traverse/tables.ts
+++ b/src/includer/traverse/tables.ts
@@ -6,6 +6,7 @@ import {concatNewLine} from '../utils';
import {OpenJSONSchema, OpenJSONSchemaDefinition} from '../models';
import {collectRefs, extractOneOfElements, inferType, typeToText} from './types';
import {prepareComplexDescription} from './description';
+import {getOrderedParamOrPropList} from '../ui/presentationUtils/orderedProps/getOrderedPropList';
type TableRow = [string, string];
@@ -56,7 +57,16 @@ function prepareObjectSchemaTable(schema: OpenJSONSchema): PrepareObjectSchemaTa
const result: PrepareObjectSchemaTableResult = {rows: [], refs: []};
- Object.entries(merged.properties || {}).forEach(([key, v]) => {
+ const wellOrderedProperties = getOrderedParamOrPropList({
+ propList: Object.entries(merged.properties || {}),
+ iteratee: ([propName]) => ({
+ paramOrPropName: propName,
+ isRequired: isRequired(propName, merged),
+ }),
+ shouldApplyLexSort: true,
+ });
+
+ wellOrderedProperties.forEach(([key, v]) => {
const value = RefsService.merge(v);
const name = tableParameterName(key, isRequired(key, merged));
const {type, description, ref, runtimeRef} = prepareTableRowData(value, key, tableRef);
diff --git a/src/includer/ui/common.ts b/src/includer/ui/common.ts
index 42a151d..98da6d2 100644
--- a/src/includer/ui/common.ts
+++ b/src/includer/ui/common.ts
@@ -32,7 +32,7 @@ function link(text: string, src: string) {
}
function title(depth: TitleDepth) {
- return (content?: string) => content?.length && '#'.repeat(depth) + ` ${content}`;
+ return (content?: string) => (content?.length ? '#'.repeat(depth) + ` ${content}` : '');
}
function body(text?: string) {
diff --git a/src/includer/ui/endpoint.ts b/src/includer/ui/endpoint.ts
index f4fe36e..3163b01 100644
--- a/src/includer/ui/endpoint.ts
+++ b/src/includer/ui/endpoint.ts
@@ -2,6 +2,8 @@ import stringify from 'json-stringify-safe';
import RefsService from '../services/refs';
import {dump} from 'js-yaml';
+import groupBy from 'lodash/groupBy';
+
import {
COOKIES_SECTION_NAME,
HEADERS_SECTION_NAME,
@@ -23,6 +25,7 @@ import {
import {
Endpoint,
+ In,
OpenJSONSchema,
Parameter,
Parameters,
@@ -49,6 +52,7 @@ import {
tabs,
title,
} from './common';
+import {getOrderedParamOrPropList} from './presentationUtils/orderedProps/getOrderedPropList';
function endpoint(data: Endpoint, sandboxPlugin: {host?: string; tabName?: string} | undefined) {
// try to remember, which tables we are already printed on page
@@ -161,6 +165,18 @@ function request(data: Endpoint) {
return block(result);
}
+function getParameterSourceTableContents(parameterList: readonly Parameter[]) {
+ const rowsAndRefs = parameterList.map((param) => parameterRow(param));
+
+ const additionalRefs = rowsAndRefs
+ .flatMap(({ref}) => ref)
+ .filter((maybeRef): maybeRef is string => typeof maybeRef !== 'undefined');
+
+ const contentRows = rowsAndRefs.map(({cells}) => cells);
+
+ return {additionalRefs, contentRows};
+}
+
function parameters(pagePrintedRefs: Set
, params?: Parameters) {
const sections = {
path: PATH_PARAMETERS_SECTION_NAME,
@@ -168,26 +184,47 @@ function parameters(pagePrintedRefs: Set, params?: Parameters) {
header: HEADERS_SECTION_NAME,
cookie: COOKIES_SECTION_NAME,
};
- const tables = [];
- for (const [inValue, heading] of Object.entries(sections)) {
- const inParams = params?.filter((param: Parameter) => param.in === inValue);
- if (inParams?.length) {
- const rows: string[][] = [];
- const tableRefs: TableRef[] = [];
- for (const param of inParams) {
- const {cells, ref} = parameterRow(param);
- rows.push(cells);
- if (ref) {
- // there may be enums, which should be printed in separate tables
- tableRefs.push(...ref);
- }
- }
- tables.push(title(3)(heading));
- tables.push(table([['Name', 'Description'], ...rows]));
- tables.push(...printAllTables(pagePrintedRefs, tableRefs));
- }
- }
- return block(tables);
+
+ const partitionedParameters = groupBy(params, (parameterSpec) => parameterSpec.in) as Record<
+ In,
+ Parameter[] | undefined
+ >;
+
+ const content = Object.keys(sections)
+ .map(
+ (parameterSource) =>
+ [
+ parameterSource as In,
+ partitionedParameters[parameterSource as In] ?? [],
+ ] as const,
+ )
+ .filter(([, parameterList]) => parameterList.length)
+ .reduce((contentAccumulator, [parameterSource, parameterList]) => {
+ const wellOrderedParameters = getOrderedParamOrPropList({
+ propList: parameterList,
+ iteratee: ({name, required}) => ({
+ paramOrPropName: name,
+ // required can actually be `undefined` in runtime
+ isRequired: Boolean(required),
+ }),
+ shouldApplyLexSort: true,
+ });
+
+ const {contentRows, additionalRefs} =
+ getParameterSourceTableContents(wellOrderedParameters);
+
+ const tableHeading = sections[parameterSource];
+
+ contentAccumulator.push(
+ title(3)(tableHeading),
+ table([['Name', 'Description'], ...contentRows]),
+ ...printAllTables(pagePrintedRefs, additionalRefs),
+ );
+
+ return contentAccumulator;
+ }, []);
+
+ return block(content);
}
function parameterRow(param: Parameter): {cells: string[]; ref?: TableRef[]} {
@@ -220,15 +257,15 @@ function openapiBody(pagePrintedRefs: Set, obj?: Schema) {
const {type = 'schema', schema} = obj;
const sectionTitle = title(3)('Body');
- let result: any[] = [sectionTitle];
+ let result: (string | null)[] = [sectionTitle];
if (isPrimitive(schema.type)) {
result = [
...result,
type,
`${bold('Type:')} ${schema.type}`,
- schema.format && `${bold('Format:')} ${schema.format}`,
- schema.description && `${bold('Description:')} ${schema.description}`,
+ schema.format ? `${bold('Format:')} ${schema.format}` : null,
+ schema.description ? `${bold('Description:')} ${schema.description}` : null,
];
return block(result);
diff --git a/src/includer/ui/presentationUtils/orderedProps/getOrderedPropList.test.ts b/src/includer/ui/presentationUtils/orderedProps/getOrderedPropList.test.ts
new file mode 100644
index 0000000..737e1e0
--- /dev/null
+++ b/src/includer/ui/presentationUtils/orderedProps/getOrderedPropList.test.ts
@@ -0,0 +1,20 @@
+import {getOrderedParamOrPropList} from './getOrderedPropList';
+
+const mockIteratee = (s: string) => ({
+ paramOrPropName: s.replace(/\*$/, ''),
+ isRequired: s.endsWith('*'),
+});
+
+describe('getOrderedPropList helper function', () => {
+ it('preserves lexicographic order even after hoisting the required entries', () => {
+ const mockElements = ['traits', 'weight*', 'id*', 'species', 'xenoClass*'];
+
+ const ordered = getOrderedParamOrPropList({
+ propList: mockElements,
+ iteratee: mockIteratee,
+ shouldApplyLexSort: true,
+ });
+
+ expect(ordered).toEqual(['id*', 'weight*', 'xenoClass*', 'species', 'traits']);
+ });
+});
diff --git a/src/includer/ui/presentationUtils/orderedProps/getOrderedPropList.ts b/src/includer/ui/presentationUtils/orderedProps/getOrderedPropList.ts
new file mode 100644
index 0000000..eb5691e
--- /dev/null
+++ b/src/includer/ui/presentationUtils/orderedProps/getOrderedPropList.ts
@@ -0,0 +1,45 @@
+import sortBy from 'lodash/sortBy';
+import {hoistRequiredParamsOrProps} from './hoistRequired';
+
+type IterateeReturn = {
+ paramOrPropName: string;
+ isRequired: boolean;
+};
+
+type Iteratee = (listElement: T) => IterateeReturn;
+
+type GetOrderedParamOrPropListArguments = {
+ /**
+ * List of parameters/object schema props to process and order.
+ */
+ propList: readonly T[];
+ /**
+ * A getter function to resolve whether a param/prop is required, as well as its name.
+ */
+ iteratee: Iteratee;
+ /**
+ * Whether or not to apply lexicographic sort before hoisting the required properties.
+ */
+ shouldApplyLexSort: boolean;
+};
+
+/**
+ * Get a well-ordered list of parameters/object schema props (i.e., required params/props hoisted to
+ * the start of the list, lexicographic sort applied as necessary).
+ * @param {GetOrderedParamOrPropListArguments} param0 Arguments for the operation.
+ * @returns {ReadonlyArray} The resulting well-ordered list.
+ */
+export const getOrderedParamOrPropList = ({
+ propList,
+ iteratee,
+ shouldApplyLexSort,
+}: GetOrderedParamOrPropListArguments): readonly T[] => {
+ const preprocessed = shouldApplyLexSort
+ ? sortBy(propList, (listElement) => iteratee(listElement).paramOrPropName)
+ : propList;
+
+ return hoistRequiredParamsOrProps(
+ preprocessed,
+ (listElement) => iteratee(listElement).isRequired,
+ );
+};
diff --git a/src/includer/ui/presentationUtils/orderedProps/hoistRequired.test.ts b/src/includer/ui/presentationUtils/orderedProps/hoistRequired.test.ts
new file mode 100644
index 0000000..d1c4639
--- /dev/null
+++ b/src/includer/ui/presentationUtils/orderedProps/hoistRequired.test.ts
@@ -0,0 +1,29 @@
+import {hoistRequiredParamsOrProps} from './hoistRequired';
+
+const mockIsRequiredGetter = (s: string) => s.endsWith('*');
+
+describe('hoistRequired helper function', () => {
+ it('preserves original order when all original properties are optional', () => {
+ const mockElements = ['idLte', 'idGte', 'nameLte', 'nameGte', 'limit'];
+
+ const ordered = hoistRequiredParamsOrProps(mockElements, mockIsRequiredGetter);
+
+ expect(ordered).toEqual(mockElements);
+ });
+
+ it('preserves original order when all original properties are required', () => {
+ const mockElements = ['id*', 'fullName*', 'salary*', 'dept*'];
+
+ const ordered = hoistRequiredParamsOrProps(mockElements, mockIsRequiredGetter);
+
+ expect(ordered).toEqual(mockElements);
+ });
+
+ it('does actually hoist required properties to the top of the list', () => {
+ const mockElements = ['catName*', 'hasThoughts', 'isLazy', 'breed*', 'likesCatnip*'];
+
+ const ordered = hoistRequiredParamsOrProps(mockElements, mockIsRequiredGetter);
+
+ expect(ordered).toEqual(['catName*', 'breed*', 'likesCatnip*', 'hasThoughts', 'isLazy']);
+ });
+});
diff --git a/src/includer/ui/presentationUtils/orderedProps/hoistRequired.ts b/src/includer/ui/presentationUtils/orderedProps/hoistRequired.ts
new file mode 100644
index 0000000..f3cbbe0
--- /dev/null
+++ b/src/includer/ui/presentationUtils/orderedProps/hoistRequired.ts
@@ -0,0 +1,25 @@
+type IsRequiredGetter = (element: T) => boolean;
+
+const makeSortComparator =
+ (isRequiredGetter: IsRequiredGetter) =>
+ (lhs: T, rhs: T): number => {
+ const [isLhsRequired, isRhsRequired] = [lhs, rhs].map(isRequiredGetter).map(Boolean);
+
+ // In this scenario, we define an element's "magnitude" as 1 if it's required,
+ // 0 otherwise. Normal math comparison then can be applied.
+ // However, the sort order should be reversed, since bigger (required)
+ // elements should come first in the resulting list, hence we use |rhs| - |lhs|
+ return Number(isRhsRequired) - Number(isLhsRequired);
+ };
+
+/**
+ * Hoist required parameters or object properties, preserving the original order otherwise.
+ * @param {ReadonlyArray} propList A list of params/properties that need to be ordered.
+ * @param {IsRequiredGetter} isRequiredGetter A function which will be called on each element of
+ * `propList` to determine whether a property is required or not.
+ * @returns {ReadonlyArray} Ordered prop/param list.
+ */
+export const hoistRequiredParamsOrProps = (
+ propList: readonly T[],
+ isRequiredGetter: IsRequiredGetter,
+): readonly T[] => [...propList].sort(makeSortComparator(isRequiredGetter));
diff --git a/src/includer/ui/presentationUtils/partitionParams.ts b/src/includer/ui/presentationUtils/partitionParams.ts
new file mode 100644
index 0000000..e69de29