Update both OpenAPI specs from ld main - #172
Merged
Merged
Conversation
Re-vendors specs/hosted-v1.yaml and specs/dolthub-v2.yaml from ld main
(781c0ea3435).
Hosted v1 gains three Deployment endpoints and four schemas:
GET /deployments/{owner}/{deployment}/config getDeploymentConfig
GET /deployments/{owner}/{deployment}/backups listDeploymentBackups
POST /deployments/{owner}/{deployment}/disable disableDeployment
plus Backup, ConfigSetting, DeploymentConfig, and DisableAccepted. The
hand-written v1 overview picks all three up in its endpoint table, and the
long-running-work section now covers disable — it returns 202 with the
deployment in `stopping` and is polled the same way a create is — along with
the warning that disabling tears down instances and storage.
DoltHub v2 has no structural change: same 22 operations and 40 schemas. Its
diff is the RequestId header being hoisted into a shared component and error
responses being declared as application/problem+json.
That content-type change exposed a generator bug. Error bodies were looked up
under application/json only, so every error row lost its Problem schema link
the moment the declaration became application/problem+json. The hosted spec
already used problem+json, which means those rows have been blank since the
hosted docs landed. Media-type lookups now go through a jsonBody() helper that
accepts either, so both APIs link Problem again.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Re-vendors specs/hosted-v1.yaml from ld main (3654e2df4bd), which adds two
Deployment endpoints and two schemas:
POST /deployments/{owner}/{deployment}/instances addDeploymentInstance
DELETE /deployments/{owner}/{deployment}/instances/{id} deleteDeploymentInstance
plus AddInstanceRequest and InstanceDeleteAccepted. Hosted v1 is now 11
operations and 23 schemas. dolthub-v2.yaml is unchanged at this ld commit.
Both endpoints are added to the hand-written overview's endpoint table, and
Long-running work gains a paragraph for them. They return 202 like create and
disable, but unlike those there is no per-instance state field to poll, so
progress is observed through the instance list instead: an added replica is
ready when it reports a host, and a removed one is gone when it drops off the
list, which only reports instances that aren't stopped.
This is the first DELETE in either generated API doc; its badge and its
body-less curl example both render correctly.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The Parameters table disappeared from the instance endpoints. The generator read only operation.parameters, but the spec now declares owner/deployment (and id) on the path item, which OpenAPI 3.1 §4.8.9 says every operation under that path inherits. Hoisting them there is the natural thing to do once a path has more than one method, which is what adding POST /instances did — so the same commit that introduced the new endpoints silently stripped the parameters off the existing GET. endpointBlock now merges the path item's parameters with the operation's, with operation-level entries overriding an inherited one of the same name and location, per the spec. The merged set also feeds the curl example, so a required query parameter declared on a path item still lands in the URL. Restores 2 parameters on listDeploymentInstances and documents 2 on addDeploymentInstance and 3 on deleteDeploymentInstance. Audited against the spec: all 11 hosted operations now render a Parameters table exactly when the spec defines parameters for them. DoltHub v2 declares none at the path-item level, so its output is byte-identical. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Re-vendors
specs/hosted-v1.yamlandspecs/dolthub-v2.yamlfrom ldmain(781c0ea3435) and regenerates. Both had drifted.Hosted v1 — 3 endpoints, 4 schemas
Plus
Backup,ConfigSetting,DeploymentConfig,DisableAccepted. All carry the existingDeploymenttag, so the nav is unchanged.The v1 overview is hand-written, so it doesn't pick these up automatically — I added all three to its endpoint table and extended Long-running work, since
disablereturns202with the deployment instoppingand is polled exactly like a create. It also carries the spec's warning that disabling tears down instances and their storage.DoltHub v2 — prose only, but it caught a bug
No structural change: same 22 operations, 40 schemas. The spec diff hoists
RequestIdinto a shared header component and redeclares error responses asapplication/problem+json. The only generated change isProblem.typebecoming required.That content-type change broke the generated docs. Error bodies were looked up under
application/jsononly, so every error row silently lost itsProblemschema link — caught in the regenerated diff:Media-type lookups now go through a
jsonBody()helper accepting either type. The v2 endpoint pages net to zero diff in this PR, which confirms the links were restored exactly.The same bug means the hosted error rows have been blank since those docs landed — that spec already used
problem+json. So this fix repairs v2 and improves hosted at the same time; theProblemlinks appearing inhosted/api/v1/*.mdare new.Verification
Endpoint table matches all 9 hosted operations exactly, every referenced model anchor resolves on both trees, 312 internal links check clean, frontmatter passes, 202 pages build, 90/90 Cypress.