Use x-navtitle and x-slug extensions for tags. Close #50

src/__snapshots__/tags.test.ts.snap

@@ -0,0 +1,219 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`tags rendering renders basic tag: index.md 1`] = `
+"# basic
+
+basic tag
+
+## Endpoints
+
+- [name](name.md)
+
+<!-- markdownlint-disable-file -->"
+`;
+
+exports[`tags rendering renders basic tag: name.md 1`] = `
+"<div class="openapi">
+
+# name
+
+## 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>
+
+## Responses
+
+<div class="openapi__response__code__200">
+
+## 200 OK
+
+Base 200 response
+
+<div class="openapi-entity">
+
+### Body
+
+{% cut "application/json" %}
+
+
+\`\`\`json
+{
+    "id": 0,
+    "title": "string"
+}
+\`\`\`
+
+
+{% endcut %}
+
+
+#|||
+ **Name** 
+|
+ **Description** 
+||
+
+||
+ id 
+|
+ **Type:** number
+
+
+
+||
+
+||
+ title 
+|
+ **Type:** string
+
+
+
+|||#
+
+</div>
+
+</div>
+<!-- markdownlint-disable-file -->
+
+</div>"
+`;
+
+exports[`tags rendering renders basic tag: toc 1`] = `
+"name: openapi
+items:
+  - name: Overview
+    href: index.md
+  - name: basic
+    items:
+      - name: Overview
+        href: basic/index.md
+      - href: basic/name.md
+        name: name
+  - href: test-parameters.md
+    name: parameters test
+"
+`;
+
+exports[`tags rendering uses custom name from tag and title from operation: index.md 1`] = `
+"# Title from x-navtitle in operation
+
+## Endpoints
+
+- [name](name.md)
+
+<!-- markdownlint-disable-file -->"
+`;
+
+exports[`tags rendering uses custom name from tag and title from operation: toc 1`] = `
+"name: openapi
+items:
+  - name: Overview
+    href: index.md
+  - name: Title from x-navtitle in operation
+    items:
+      - name: Overview
+        href: slug/index.md
+      - href: slug/name.md
+        name: name
+  - href: test-parameters.md
+    name: parameters test
+"
+`;
+
+exports[`tags rendering uses custom name from tag: index.md 1`] = `
+"# TagName
+
+## Endpoints
+
+- [name](name.md)
+
+<!-- markdownlint-disable-file -->"
+`;
+
+exports[`tags rendering uses custom name from tag: toc 1`] = `
+"name: openapi
+items:
+  - name: Overview
+    href: index.md
+  - name: TagName
+    items:
+      - name: Overview
+        href: slug/index.md
+      - href: slug/name.md
+        name: name
+  - href: test-parameters.md
+    name: parameters test
+"
+`;
+
+exports[`tags rendering uses custom title from operation: index.md 1`] = `
+"# Title from x-navtitle in operation
+
+## Endpoints
+
+- [name](name.md)
+
+<!-- markdownlint-disable-file -->"
+`;
+
+exports[`tags rendering uses custom title from operation: toc 1`] = `
+"name: openapi
+items:
+  - name: Overview
+    href: index.md
+  - name: Title from x-navtitle in operation
+    items:
+      - name: Overview
+        href: TagName/index.md
+      - href: TagName/name.md
+        name: name
+  - href: test-parameters.md
+    name: parameters test
+"
+`;
+
+exports[`tags rendering uses custom title from tag override title from operation: index.md 1`] = `
+"# Title from tag
+
+## Endpoints
+
+- [name](name.md)
+
+<!-- markdownlint-disable-file -->"
+`;
+
+exports[`tags rendering uses custom title from tag override title from operation: toc 1`] = `
+"name: openapi
+items:
+  - name: Overview
+    href: index.md
+  - name: Title from tag
+    items:
+      - name: Overview
+        href: TagName/index.md
+      - href: TagName/name.md
+        name: name
+  - href: test-parameters.md
+    name: parameters test
+"
+`;

src/__tests__/__helpers__/run.ts

@@ -4,6 +4,17 @@ import {when} from 'jest-when';
 import {dump} from 'js-yaml';
 import {virtualFS} from './virtualFS';
 import nodeFS from 'fs';
+import { TAG_ID_FIELD, TAG_NAMES_FIELD } from '../../includer/constants';
+
+declare module 'openapi-types' {
+    // eslint-disable-next-line @typescript-eslint/no-namespace
+    namespace OpenAPIV3 {
+        interface TagObject {
+            [TAG_NAMES_FIELD]?: string;
+            [TAG_ID_FIELD]?: string;
+        }
+    }
+}
 
 const baseDocument = {
     openapi: '3.0.2',
@@ -37,6 +48,8 @@ export class DocumentBuilder {
     private responses: [code: number, response: OpenAPIV3.ResponseObject][] = [];
     private parameters: OpenAPIV3.ParameterObject[] = [];
     private components: Record<string, OpenAPIV3.SchemaObject> = {};
+    private tags: Array<OpenAPIV3.TagObject> = [];
+    private navTitles?: string[];
     private requestBody?: OpenAPIV3.RequestBodyObject = undefined;
 
     constructor(id: string) {
@@ -86,6 +99,18 @@ export class DocumentBuilder {
         return this;
     }
 
+    tag(schema: OpenAPIV3.TagObject) {
+        this.tags.push(schema);
+
+        return this;
+    }
+
+    navTitle(title: string) {
+        (this.navTitles ??= []).push(title);
+
+        return this;
+    }
+
     build(): string {
         if (!this.responses.length) {
             throw new Error("Test case error: endpoint can't have no responses");
@@ -99,13 +124,17 @@ export class DocumentBuilder {
                         requestBody: this.requestBody,
                         operationId: this.id,
                         responses: Object.fromEntries(this.responses),
+                        tags: this.tags.map((tag) => tag.name),
+                        // @ts-expect-error custom extension
+                        [TAG_NAMES_FIELD]: this.navTitles,
                     },
                     parameters: this.parameters,
                 },
             },
             components: {
                 schemas: this.components,
             },
+            tags: this.tags,
         };
 
         return dump(spec);

src/__tests__/tags.test.ts

@@ -0,0 +1,96 @@
+import {DocumentBuilder, run} from './__helpers__/run';
+
+describe('tags rendering', () => {
+    const response = {
+        description: 'Base 200 response',
+        schema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'number',
+                },
+                title: {
+                    type: 'string',
+                },
+            },
+        },
+    } as const;
+
+    it('renders basic tag', async() => {
+        const spec = new DocumentBuilder('name')
+            .response(200, response)
+            .tag({
+                name: 'basic',
+                description: 'basic tag',
+            })
+            .build();
+
+        const fs = await run(spec);
+
+        expect(fs.match('toc.yaml')).toMatchSnapshot('toc');
+        expect(fs.match('basic/index.md')).toMatchSnapshot('index.md');
+        expect(fs.match('basic/name.md')).toMatchSnapshot('name.md');
+    });
+
+    it('uses custom title from operation', async() => {
+        const spec = new DocumentBuilder('name')
+            .response(200, response)
+            .tag({
+                name: 'TagName',
+            })
+            .navTitle('Title from x-navtitle in operation')
+            .build();
+
+        const fs = await run(spec);
+
+        expect(fs.match('toc.yaml')).toMatchSnapshot('toc');
+        expect(fs.match('TagName/index.md')).toMatchSnapshot('index.md');
+    });
+
+    it('uses custom title from tag override title from operation', async() => {
+        const spec = new DocumentBuilder('name')
+            .response(200, response)
+            .tag({
+                name: 'TagName',
+                'x-navtitle': 'Title from tag'
+            })
+            .navTitle('Title from x-navtitle in operation')
+            .build();
+
+        const fs = await run(spec);
+
+        expect(fs.match('toc.yaml')).toMatchSnapshot('toc');
+        expect(fs.match('TagName/index.md')).toMatchSnapshot('index.md');
+    });
+
+    it('uses custom name from tag', async() => {
+        const spec = new DocumentBuilder('name')
+            .response(200, response)
+            .tag({
+                name: 'TagName',
+                'x-slug': 'slug'
+            })
+            .build();
+
+        const fs = await run(spec);
+
+        expect(fs.match('toc.yaml')).toMatchSnapshot('toc');
+        expect(fs.match('slug/index.md')).toMatchSnapshot('index.md');
+    });
+
+    it('uses custom name from tag and title from operation', async() => {
+        const spec = new DocumentBuilder('name')
+            .response(200, response)
+            .tag({
+                name: 'TagName',
+                'x-slug': 'slug',
+            })
+            .navTitle('Title from x-navtitle in operation')
+            .build();
+
+        const fs = await run(spec);
+
+        expect(fs.match('toc.yaml')).toMatchSnapshot('toc');
+        expect(fs.match('slug/index.md')).toMatchSnapshot('index.md');
+    });
+});

src/includer/constants.ts

@@ -5,6 +5,7 @@ export enum LeadingPageMode {
     Leaf = 'leaf',
 }
 export const EOL = '\n';
+export const TAG_ID_FIELD = 'x-slug';
 export const TAG_NAMES_FIELD = 'x-navtitle';
 export const BLOCK = EOL.repeat(2);
 export const INFO_TAB_NAME = 'Info';