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

src/__snapshots__/tags.test.ts.snap

@@ -0,0 +1,53 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`tags rendering renders tag and toc: basic 1`] = `
+"# basic
+
+basic tag
+
+## Endpoints
+
+- [tags](tags.md)
+
+<!-- markdownlint-disable-file -->"
+`;
+
+exports[`tags rendering renders tag and toc: toc 1`] = `
+"name: openapi
+items:
+  - name: Overview
+    href: index.md
+  - name: basic
+    items:
+      - name: Overview
+        href: basic/index.md
+      - href: basic/tags.md
+        name: tags
+  - name: Alternate title
+    items:
+      - name: Overview
+        href: navtitle/index.md
+      - href: navtitle/tags.md
+        name: tags
+  - name: Normal title
+    items:
+      - name: Overview
+        href: normal/index.md
+      - href: normal/tags.md
+        name: tags
+  - href: test-parameters.md
+    name: parameters test
+"
+`;
+
+exports[`tags rendering renders tag and toc: weird 1`] = `
+"# Normal title
+
+weird tag with normal slug
+
+## Endpoints
+
+- [tags](tags.md)
+
+<!-- markdownlint-disable-file -->"
+`;

src/__tests__/__helpers__/run.ts

@@ -5,6 +5,16 @@ import {dump} from 'js-yaml';
 import {virtualFS} from './virtualFS';
 import nodeFS from 'fs';
 
+declare module 'openapi-types' {
+    // eslint-disable-next-line @typescript-eslint/no-namespace
+    namespace OpenAPIV3 {
+        interface TagObject {
+            'x-navtitle'?: string;
+            'x-slug'?: string;
+        }
+    }
+}
+
 const baseDocument = {
     openapi: '3.0.2',
     info: {
@@ -37,6 +47,7 @@ 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 requestBody?: OpenAPIV3.RequestBodyObject = undefined;
 
     constructor(id: string) {
@@ -86,6 +97,12 @@ export class DocumentBuilder {
         return this;
     }
 
+    tag(schema: OpenAPIV3.TagObject) {
+        this.tags.push(schema);
+
+        return this;
+    }
+
     build(): string {
         if (!this.responses.length) {
             throw new Error("Test case error: endpoint can't have no responses");
@@ -99,13 +116,15 @@ export class DocumentBuilder {
                         requestBody: this.requestBody,
                         operationId: this.id,
                         responses: Object.fromEntries(this.responses),
+                        tags: this.tags.map((tag) => tag.name),
                     },
                     parameters: this.parameters,
                 },
             },
             components: {
                 schemas: this.components,
             },
+            tags: this.tags,
         };
 
         return dump(spec);

src/__tests__/tags.test.ts

@@ -0,0 +1,51 @@
+import {DocumentBuilder, run} from './__helpers__/run';
+
+const name = 'tags';
+describe('tags rendering', () => {
+    it('renders tag and toc', async () => {
+        const spec = new DocumentBuilder(name)
+            .response(200, {
+                description: 'Base 200 response',
+                schema: {
+                    type: 'object',
+                    properties: {
+                        type: {
+                            type: 'string',
+                        },
+                        foo: {
+                            type: 'string',
+                        },
+                    },
+                },
+            })
+            .tag({
+                name: 'basic',
+                description: 'basic tag',
+            })
+            .tag({
+                name: 'navtitle',
+                'x-navtitle': 'Alternate title',
+            })
+            .tag({
+                name: 'weird',
+                description: 'weird tag with normal slug',
+                'x-slug': 'normal',
+                'x-navtitle': 'Normal title',
+            })
+            .build();
+
+        const fs = await run(spec);
+
+        const toc = fs.match('toc.yaml');
+
+        expect(toc).toMatchSnapshot('toc');
+
+        const tag = fs.match('basic/index.md');
+
+        expect(tag).toMatchSnapshot('basic');
+
+        const tag2 = fs.match('normal/index.md');
+
+        expect(tag2).toMatchSnapshot('weird');
+    });
+});

src/includer/index.ts

@@ -155,7 +155,7 @@ async function generateToc(params: GenerateTocParams): Promise<void> {
         items: [],
     };
 
-    tags.forEach((tag, id) => {
+    tags.forEach((tag) => {
         // eslint-disable-next-line no-shadow
         const {name, endpoints: endpointsOfTag} = tag;
 
@@ -165,7 +165,7 @@ async function generateToc(params: GenerateTocParams): Promise<void> {
         };
 
         const custom = ArgvService.tag(tag.name);
-        const customId = custom?.alias || id;
+        const customId = custom?.alias || tag.id;
 
         section.items = endpointsOfTag.map((endpoint) => handleEndpointRender(endpoint, customId));
 
@@ -273,11 +273,11 @@ async function generateContent(params: GenerateContentParams): Promise<void> {
         });
     }
 
-    spec.tags.forEach((tag, id) => {
+    spec.tags.forEach((tag) => {
         const {endpoints} = tag;
 
         const custom = ArgvService.tag(tag.name);
-        const customId = custom?.alias || id;
+        const customId = custom?.alias || tag.id;
 
         endpoints.forEach((endpoint) => {
             results.push(handleEndpointIncluder(endpoint, join(writePath, customId), sandbox));

src/includer/models.ts

@@ -159,6 +159,8 @@ export type Tag = {
     name: string;
     description?: string;
     endpoints: Endpoints;
+    'x-navtitle'?: string;
+    'x-slug'?: string;
 };
 
 export type Endpoints = Endpoint[];

src/includer/parsers.ts

@@ -110,6 +110,15 @@ function tagsFromSpec(spec: OpenAPISpec): Map<string, Tag> {
         }
     }
 
+    parsed.forEach((tag: Tag) => {
+        if (tag['x-navtitle']) {
+            tag.name = tag['x-navtitle'];
+        }
+        if (tag['x-slug']) {
+            tag.id = tag['x-slug'];
+        }
+    });
+
     return parsed;
 }
 const opid = (path: string, method: string, id?: string) => slugify(id ?? [path, method].join('-'));