Omit endpoint parameters marked with x-hidden

.eslintrc.js

@@ -7,7 +7,7 @@ module.exports = {
             parser: '@typescript-eslint/parser',
             parserOptions: {
                 sourceType: 'module',
-                project: ['./tsconfig.test.json', './tsconfig.json'],
+                project: ['./src/__tests__/tsconfig.json', './tsconfig.json'],
                 tsconfigRootDir: __dirname,
             },
         },

src/@types/oasVendorExtensions.d.ts

@@ -0,0 +1,13 @@
+import 'openapi-types';
+
+declare module 'openapi-types' {
+    namespace OpenAPIV3 {
+        interface BaseSchemaObject {
+            'x-hidden'?: boolean;
+        }
+
+        interface ParameterBaseObject {
+            'x-hidden'?: boolean;
+        }
+    }
+}

src/__snapshots__/hidden/endpointParameters.test.ts.snap

@@ -0,0 +1,147 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Endpoint parameter tables should be omitted if all of their respective parameters are marked with \`x-hidden\` 1`] = `
+"<div class="openapi">
+
+# HiddenEndpointParameters
+
+## Request
+
+<div class="openapi__requests">
+
+<div class="openapi__request__wrapper" style="--method: var(--dc-openapi-methods-post);margin-bottom: 12px">
+
+<div class="openapi__request">
+
+POST {.openapi__method} 
+\`\`\`
+http://localhost:8080/test
+\`\`\`
+
+
+
+</div>
+
+Generated server url
+
+</div>
+
+</div>
+
+### Cookies
+
+#|||
+ **Name** 
+|
+ **Description** 
+||
+
+||
+ accessToken 
+|
+ **Type:** string
+
+Access token 
+|||#
+
+## Responses
+
+<div class="openapi__response__code__204">
+
+## 204 No Content
+
+<div class="openapi-entity">
+
+### Body
+
+{% cut "application/json" %}
+
+
+\`\`\`json
+{}
+\`\`\`
+
+
+{% endcut %}
+
+
+</div>
+
+</div>
+<!-- markdownlint-disable-file -->
+
+</div>"
+`;
+
+exports[`Endpoint parameter tables should not include parameters marked with \`x-hidden\` in the spec 1`] = `
+"<div class="openapi">
+
+# HiddenEndpointParameters
+
+## Request
+
+<div class="openapi__requests">
+
+<div class="openapi__request__wrapper" style="--method: var(--dc-openapi-methods-post);margin-bottom: 12px">
+
+<div class="openapi__request">
+
+POST {.openapi__method} 
+\`\`\`
+http://localhost:8080/test
+\`\`\`
+
+
+
+</div>
+
+Generated server url
+
+</div>
+
+</div>
+
+### Query parameters
+
+#|||
+ **Name** 
+|
+ **Description** 
+||
+
+||
+ name 
+|
+ **Type:** string
+
+Name for the requested star 
+|||#
+
+## Responses
+
+<div class="openapi__response__code__204">
+
+## 204 No Content
+
+<div class="openapi-entity">
+
+### Body
+
+{% cut "application/json" %}
+
+
+\`\`\`json
+{}
+\`\`\`
+
+
+{% endcut %}
+
+
+</div>
+
+</div>
+<!-- markdownlint-disable-file -->
+
+</div>"
+`;

src/__snapshots__/hidden/objectProps.test.ts.snap

@@ -0,0 +1,102 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Properties in object schemas marked with \`x-hidden\` should not be rendered in the resulting markdown 1`] = `
+"<div class="openapi">
+
+# HiddenObjectProperties
+
+## Request
+
+<div class="openapi__requests">
+
+<div class="openapi__request__wrapper" style="--method: var(--dc-openapi-methods-post);margin-bottom: 12px">
+
+<div class="openapi__request">
+
+POST {.openapi__method} 
+\`\`\`
+http://localhost:8080/test
+\`\`\`
+
+
+
+</div>
+
+Generated server url
+
+</div>
+
+</div>
+
+<div class="openapi-entity">
+
+### Body
+
+{% cut "application/json" %}
+
+
+\`\`\`json
+{
+    "luminosityClass": "string",
+    "name": "string"
+}
+\`\`\`
+
+
+{% endcut %}
+
+
+#|||
+ **Name** 
+|
+ **Description** 
+||
+
+||
+ luminosityClass 
+|
+ **Type:** string
+
+Morgan-Keenan luminosity class for this star
+
+||
+
+||
+ name 
+|
+ **Type:** string
+
+Name of this star
+
+|||#
+
+</div>
+
+## Responses
+
+<div class="openapi__response__code__204">
+
+## 204 No Content
+
+<div class="openapi-entity">
+
+### Body
+
+{% cut "application/json" %}
+
+
+\`\`\`json
+{}
+\`\`\`
+
+
+{% endcut %}
+
+
+</div>
+
+</div>
+<!-- markdownlint-disable-file -->
+
+</div>"
+`;

src/__tests__/hidden/endpointParameters.test.ts

@@ -0,0 +1,94 @@
+import {DocumentBuilder, run} from '../__helpers__/run';
+
+const mockDocumentName = 'HiddenEndpointParameters';
+
+describe('Endpoint parameter tables', () => {
+    it('should not include parameters marked with `x-hidden` in 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',
+                description: 'Internal ID for the requested star',
+                schema: {
+                    type: 'string',
+                    format: 'uuid',
+                },
+                'x-hidden': true,
+            })
+            .parameter({
+                in: 'query',
+                name: 'catalogueCCDM',
+                description: 'CCDM designation for the requested star',
+                schema: {
+                    type: 'string',
+                },
+                'x-hidden': true,
+            })
+            .response(204, {})
+            .build();
+
+        const fs = await run(spec);
+
+        const page = fs.match(mockDocumentName);
+
+        expect(page).toMatchSnapshot();
+    });
+
+    it('should be omitted if all of their respective parameters are marked with `x-hidden`', async () => {
+        const spec = new DocumentBuilder(mockDocumentName)
+            .parameter({
+                in: 'query',
+                name: 'name',
+                description: 'Name for the requested star',
+                schema: {
+                    type: 'string',
+                },
+                'x-hidden': true,
+            })
+            .parameter({
+                in: 'query',
+                name: 'id',
+                description: 'Internal ID for the requested star',
+                schema: {
+                    type: 'string',
+                    format: 'uuid',
+                },
+                'x-hidden': true,
+            })
+            .parameter({
+                in: 'query',
+                name: 'catalogueCCDM',
+                description: 'CCDM designation for the requested star',
+                schema: {
+                    type: 'string',
+                },
+                'x-hidden': true,
+            })
+            // "Query parameters" table should not be rendered; however, not all cookie params are optional
+            // so we expect this one to be rendered.
+            .parameter({
+                in: 'cookie',
+                name: 'accessToken',
+                description: 'Access token',
+                schema: {
+                    type: 'string',
+                },
+            })
+            .response(204, {})
+            .build();
+
+        const fs = await run(spec);
+
+        const page = fs.match(mockDocumentName);
+
+        expect(page).toMatchSnapshot();
+    });
+});