Skip to content

Build your personal knowledge base with Trilium Notes

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.ts
index 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.ts
index 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) {