Skip to content

Restructure OpenAPI summaries and tags - #403

Open
cmil wants to merge 3 commits into
mainfrom
openapi-summaries
Open

cmil wants to merge 3 commits into
mainfrom
openapi-summaries

Conversation

@cmil

@cmil cmil commented Oct 18, 2026

Copy link
Copy Markdown
Member

Makes the API documentation easier to navigate in Scalar and on swagger.dracor.org: endpoint summaries get a resource prefix (e.g. "Play: Network data (GEXF)"), and the catch-all public tag is split by functionality, with x-tagGroups for the Scalar sidebar.

To check:

  • The Schemathesis runs, since the tag filters were renamed (webhook → Webhook, admin → Admin)
  • Rendering in Scalar and in a plain Swagger UI, which ignores x-tagGroups and lists the tags flat

Closes #214

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Oct 18, 2026 •

Copy link
Copy Markdown

Merging this PR will leave 2 of 36 operations untested. Please review.

❌ 2 untested
🟡 1 partial
✅ 33 tested

Operations  ███████████████████░    34/36    94%
Parameters  ██████████████████░░    68/75    91%
Keywords    ██████████████████░░   90/100    90%
Responses   ██████████████████░░    74/84    88%
Examples    ██████████████████░░  289/317    91%

❌ Untested (2)

Method Path Parameters Keywords Responses Examples
❌ POST /exist/restxq/v1/webhook/github 0/5 0/7 0/1 0/0
❌ GET /exist/restxq/v1/wikidata/author/{id} 0/1 0/1 0/2 0/0

🟡 Tested (34)

Method Path Parameters Keywords Responses Examples
🟡 POST /exist/restxq/v1/corpora 1/2 8/10 4/5 0/0
🟢 GET /exist/restxq/v1/character/{id} 1/1 2/2 2/3 0/0
🟢 GET /exist/restxq/v1/corpora 1/1 2/2 2/2 0/0
🟢 DELETE /exist/restxq/v1/corpora/{corpusname} 1/1 1/1 2/3 0/7
🟢 GET /exist/restxq/v1/corpora/{corpusname} 1/1 1/1 2/2 7/7
🟢 POST /exist/restxq/v1/corpora/{corpusname} 2/2 6/6 4/6 0/7
🟢 GET /exist/restxq/v1/corpora/{corpusname}/metadata 1/1 1/1 2/2 7/7
🟢 GET /exist/restxq/v1/corpora/{corpusname}/metadata/csv 1/1 1/1 2/2 7/7
🟢 DELETE /exist/restxq/v1/corpora/{corpusname}/plays/{playname} 2/2 2/2 3/3 7/14
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname} 2/2 2/2 2/2 14/14
24 more
Method Path Parameters Keywords Responses Examples
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/characters 2/2 2/2 2/2 14/14
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/characters/csv 2/2 2/2 2/2 14/14
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/metrics 2/2 2/2 2/2 14/14
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/networkdata/csv 2/2 2/2 2/2 14/14
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/networkdata/gexf 2/2 2/2 2/2 14/14
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/networkdata/graphml 2/2 2/2 2/2 14/14
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/relations/csv 2/2 2/2 2/2 14/14
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/relations/gexf 2/2 2/2 2/2 14/14
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/relations/graphml 2/2 2/2 2/2 14/14
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/spoken-text 7/7 8/8 3/3 14/14
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/spoken-text-by-character 2/2 2/2 2/2 14/14
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/stage-directions 2/2 2/2 2/2 14/14
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/stage-directions-with-speakers 2/2 2/2 2/2 14/14
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/tei 2/2 2/2 2/2 14/14
🟢 PUT /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/tei 3/3 4/4 3/5 0/7
🟢 GET /exist/restxq/v1/corpora/{corpusname}/plays/{playname}/txt 2/2 2/2 2/2 14/14
🟢 GET /exist/restxq/v1/dts/collection 3/3 5/5 3/3 14/14
🟢 GET /exist/restxq/v1/dts/document 6/6 8/8 3/3 10/10
🟢 GET /exist/restxq/v1/dts/navigation 7/7 10/10 3/3 13/13
🟢 GET /exist/restxq/v1/id/{id} 1/1 1/1 2/2 0/0
🟢 GET /exist/restxq/v1/characters 0/0 0/0 1/1 0/0
🟢 GET /exist/restxq/v1/dts 0/0 0/0 1/1 0/0
🟢 GET /exist/restxq/v1/info 0/0 0/0 1/1 0/0
🟢 GET /exist/restxq/v1/wikidata/mixnmatch 0/0 0/0 1/1 0/0

Powered by TraceCov v0.25.5

schemathesis 4.31.1 | http://localhost:8081/exist/restxq/v1/openapi.yaml

Download full HTML report

cmil and others added 3 commits October 25, 2026 00:50
The sidebar of Scalar (and other renderers) lists endpoints by their
summary, which made individual endpoints hard to find. Summaries now
follow the pattern "Scope: Thing (format)", e.g. "Corpus: Play metadata
(CSV)" or "Play: Network data (GEXF)". This also gives the JSON and CSV
variants of the corpus metadata endpoint distinct summaries.

Details dropped from the summaries are covered by the descriptions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The public endpoints were all under a single "public" tag. They are now
split into General, Corpora, Plays, Texts, Networks and Characters, so
that for instance all data for network analysis is found in one place.
The other tags are capitalised to match.

x-tagGroups additionally groups the tags in the Scalar sidebar. Swagger
UI ignores the extension and lists the tags flat in the order of the
tags array, which is why the tags make sense without their groups.

/id/{id} is under General instead of Plays as it may also resolve other
identifiers like corpus names in the future.

The Schemathesis tag filters and the Scalar anchor links in parameter
descriptions follow the new tag names.

Closes #214

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch was successfully deployed

1 active deployment
dev — 95ad3896 Deployed Oct 24, 2026 by cmil via Deploy to dev #19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Reorganise tags in OpenAPI spec

1 participant