fix: fixes an issue preventing operations with identical IDs but diff…

…erent methods from having distinct generated pages
HiDeoo · Apr 16, 2024 · e0d681e · e0d681e
1 parent 22bc6bd
commit e0d681e
Show file tree

Hide file tree

Showing 5 changed files with 72 additions and 8 deletions.
diff --git a/packages/starlight-openapi/libs/operation.ts b/packages/starlight-openapi/libs/operation.ts
@@ -16,13 +16,20 @@ export function getOperationsByTag(document: Schema['document']) {
  continue
  }
 
- for (const method of operationHttpMethods) {
- if (!isPathItemOperation(pathItem, method)) {
+ const allOperationIds = operationHttpMethods.map((method) => {
+ return isPathItemOperation(pathItem, method) ? pathItem[method].operationId ?? pathItemPath : undefined
+ })
+
+ for (const [index, method] of operationHttpMethods.entries()) {
+ const operationId = allOperationIds[index]
+
+ if (!operationId || !isPathItemOperation(pathItem, method)) {
  continue
  }
 
  const operation = pathItem[method]
- const operationId = operation.operationId ?? pathItemPath
+ const isDuplicateOperationId = allOperationIds.filter((id) => id === operationId).length > 1
+ const operationIdSlug = slug(operationId)
 
  for (const tag of operation.tags ?? [defaultOperationTag]) {
  const operations = operationsByTag.get(tag) ?? []
@@ -32,8 +39,11 @@ export function getOperationsByTag(document: Schema['document']) {
  operation,
  path: pathItemPath,
  pathItem,
- slug: `operations/${slug(operationId)}`,
- title: operation.summary ?? operationId,
+ slug: isDuplicateOperationId
+ ? `operations/${operationIdSlug}/${slug(method)}`
+ : `operations/${operationIdSlug}`,
+ title:
+ operation.summary ?? (isDuplicateOperationId ? `${operationId} (${method.toUpperCase()})` : operationId),
  })
 
  operationsByTag.set(tag, operations)

diff --git a/packages/starlight-openapi/tests/fixtures/DocPage.ts b/packages/starlight-openapi/tests/fixtures/DocPage.ts
@@ -18,7 +18,7 @@ export class DocPage {
  }
 
  getContent() {
- return this.page.getByRole('main')
+ return this.page.locator('.sl-markdown-content')
  }
 
  async expectToHaveTitle(title: string) {

diff --git a/packages/starlight-openapi/tests/operation.test.ts b/packages/starlight-openapi/tests/operation.test.ts
@@ -54,3 +54,13 @@ test('displays overriden operation URLs for a v3.0 schema', async ({ docPage })
  await expect(docPage.getOperation().getByText('Custom server')).toBeVisible()
  expect(await docPage.getOperation().getByRole('textbox').inputValue()).toBe('custom.example.com/api/bears')
 })
+
+test('generates multiple pages for operations with identical IDs but different methods', async ({ docPage }) => {
+ await docPage.goto('/v3/animals/operations/turtles/get')
+
+ await docPage.expectToHaveTitle('List all turtles')
+
+ await docPage.goto('/v3/animals/operations/turtles/post')
+
+ await docPage.expectToHaveTitle('/turtles (POST)')
+})
diff --git a/packages/starlight-openapi/tests/webhooks.test.ts b/packages/starlight-openapi/tests/webhooks.test.ts
@@ -15,7 +15,7 @@ test('falls back to the operation ID for title', async ({ docPage }) => {
 test('displays the operation', async ({ docPage }) => {
  await docPage.goto('/v3/animals/webhooks/newanimal/')
 
- await expect(docPage.getByText('POST')).toBeVisible()
+ await expect(docPage.getContent().getByText('POST')).toBeVisible()
  expect(await docPage.getContent().getByRole('group').count()).toBe(1)
- await expect(docPage.getByText('New animal details')).toBeVisible()
+ await expect(docPage.getContent().getByText('New animal details')).toBeVisible()
 })
diff --git a/schemas/v3.0/animals.yaml b/schemas/v3.0/animals.yaml
@@ -267,6 +267,50 @@ paths:
  application/json:
  schema:
  $ref: '#/components/schemas/Error'
+ /turtles:
+ get:
+ summary: List all turtles
+ description: |
+ returns _all_ turtles
+ tags:
+ - animals
+ responses:
+ '200':
+ description: A paged array of turtles
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Animals'
+ default:
+ description: unexpected error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Error'
+ post:
+ description: Creates a new turtle
+ tags:
+ - animals
+ requestBody:
+ description: Turtle to add
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Animal'
+ responses:
+ '200':
+ description: animal response
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Animal'
+ default:
+ description: unexpected error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Error'
 webhooks:
  newAnimal:
  post: