Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
feat(docs): order and describe API groups by the spec's tags
Elian Doranbd0c10f650dd
diff --git a/apps/edit-docs/src/openapi_markdown.spec.ts b/apps/edit-docs/src/openapi_markdown.spec.tsindex a3d2b6ef4f..595431bb17 100644--- a/apps/edit-docs/src/openapi_markdown.spec.ts+++ b/apps/edit-docs/src/openapi_markdown.spec.ts@@ -124,7 +124,9 @@ describe("openApiToMarkdown", () => {it("groups operations by their first tag when the spec has tags", () => {const spec: OpenApiSpec = {info: { title: "Internal" },+ tags: [ { name: "Sync", description: "Synchronization between instances." }, { name: "Notes" } ],paths: {+ "/api/misc": { get: { tags: [ "Misc" ], responses: {} } },"/api/notes": { get: { tags: [ "Notes" ], summary: "List notes", operationId: "getNotes", responses: {} } },"/api/sync": { post: { tags: [ "Sync" ], security: [ { A: [], B: [] }, {} ], responses: {} } },"/api/login": { post: { tags: [ "Sync" ], security: [], responses: {} } },@@ -134,9 +136,13 @@ describe("openApiToMarkdown", () => {const markdown = openApiToMarkdown(spec);+ // Declared tags come first, in their declared order and with their description; the+ // others follow in order of appearance.expect(markdown).not.toContain("## Endpoints");- expect(markdown.indexOf("## Notes")).toBeLessThan(markdown.indexOf("### `GET /api/tree`"));- expect(markdown.indexOf("### `GET /api/tree`")).toBeLessThan(markdown.indexOf("## Sync"));+ expect(markdown).toContain("## Sync\n\nSynchronization between instances.\n\n### `POST /api/sync`");+ expect(markdown.indexOf("### `POST /api/login`")).toBeLessThan(markdown.indexOf("## Notes"));+ expect(markdown.indexOf("### `GET /api/tree`")).toBeLessThan(markdown.indexOf("## Misc"));+ expect(markdown.indexOf("## Misc")).toBeLessThan(markdown.indexOf("### `GET /api/misc`"));// A summary wins over the operation ID; an operation with neither is named by its route.expect(markdown).toContain("### List notes\n\n`GET /api/notes`\n\n### `GET /api/tree`");diff --git a/apps/edit-docs/src/openapi_markdown.ts b/apps/edit-docs/src/openapi_markdown.tsindex 666e9429d5..f668fe0263 100644--- a/apps/edit-docs/src/openapi_markdown.ts+++ b/apps/edit-docs/src/openapi_markdown.ts@@ -6,6 +6,8 @@export interface OpenApiSpec {info: { title: string; description?: string };paths: Record<string, PathItem>;+ /** Declares the order of the operation groups and describes them. */+ tags?: { name: string; description?: string }[];security?: SecurityRequirement[];components?: {schemas?: Record<string, Schema>;@@ -115,6 +117,10 @@ export function openApiToMarkdown(spec: OpenApiSpec): string {for (const [ group, operations ] of groupOperations(spec)) {blocks.push(`## ${group}`);+ const description = spec.tags?.find((tag) => tag.name === group)?.description;+ if (description) {+ blocks.push(description.trim());+ }for (const operation of operations) {blocks.push(...renderOperation(spec, operation));}@@ -138,9 +144,12 @@ interface OperationEntry {operation: Operation;}-/** Groups operations by their first tag, in order of appearance; a spec without tags gets one group. */+/**+ * Groups operations by their first tag: the tags the spec declares first, in that order, then the+ * others in order of appearance. Operations without a tag share one group.+ */function groupOperations(spec: OpenApiSpec) {- const groups = new Map<string, OperationEntry[]>();+ const groups = new Map<string, OperationEntry[]>((spec.tags ?? []).map((tag) => [ tag.name, [] ]));for (const [ path, pathItem ] of Object.entries(spec.paths)) {for (const method of HTTP_METHODS) {const operation = pathItem[method];@@ -155,7 +164,7 @@ function groupOperations(spec: OpenApiSpec) {}}- return groups;+ return [ ...groups ].filter(([ , entries ]) => entries.length);}function renderOperation(spec: OpenApiSpec, { method, path, pathItem, operation }: OperationEntry) {