DOC-14186: Public spec for the Sync Gateway REST APIs#962
Conversation
— includes 3.2.7 backport
There was a problem hiding this comment.
This is the Prometheus-generated file. I've moved it to partials because it's not an attachment for download. When I merge this PR forward to 3.3 and 4.0 I'll have to update the build script in App Services.
osfameron
left a comment
osfameron
left a comment
There was a problem hiding this comment.
The linked preview files don't have the <link rel="service-desc" ...> clauses.
Looks like you also need to update the shim files like rest_api_admin.adoc ?
Doh, I added the metadata to the wrong files. Good spot |
| ifdef::prerelease[:page-status: {prerelease}] | ||
| :page-role: -toc | ||
| :page-topic-type: reference | ||
| :page-service-desc: _attachments/admin.overlaid.yaml |
There was a problem hiding this comment.
Thinking about it, there's no harm in also having the service-desc linked from these overview pages, is there?
There was a problem hiding this comment.
I guess not, although those stub pages don't really hold any information about the actual spec any more?
The reason I made this mistake is that 3.2 is the first version where we got rid of the swagger-ui pages and introduced Redocly. The evolution went:
| Release 3.1 | Release 3.2 |
|---|---|
| Swagger UI pages (need service-desc) | Stub pages (don't need service-desc?) |
| Static REST API pages (need service-desc) | [removed] (replaced by partials) |
| [new] Redocly REST API pages (need service-desc) |
There was a problem hiding this comment.
So the point is, the stub pages used to contain a swagger-ui generated representation of the spec, which is why they needed the service-desc metadata. But the swagger-ui element was removed in 3.2.
|
The change looks right - I see the link in the Metrics page, but not Admin/Public. |
Yep, they are there in Admin and Public? Maybe the rebuild hadn't finished when you looked? Please feel free to refresh and check again |
osfameron
left a comment
osfameron
left a comment
There was a problem hiding this comment.
OK, weird browser issue I guess, confirmed in a different browser 👍
2 participants
Docs issue: DOC-14186
For LLM readiness, this PR adds service description metadata to the REST API reference pages for Sync Gateway.
Document previews — check the page source for
service-descmetadata:You will need the Docs Team credentials on Confluence.