Convert server keys to swagger #1405
Conversation
|
Note: This PR is intended to convert the existing documentation as-is to swagger. #1423 actually goes through to improve the documentation. This is to hopefully create a useful diff for the swagger files. |
| properties: | ||
| server_name: | ||
| type: string | ||
| description: DNS name of the homeserver |
There was a problem hiding this comment.
as per https://github.com/matrix-org/matrix-doc/blob/master/meta/documentation_style.rst#openapi, please could these end with full stops?
api/server-server/keys_query.yaml
Outdated
| type: integer | ||
| format: int64 | ||
| description: Minimum Valid Until Milliseconds | ||
| required: true # TODO: Verify |
There was a problem hiding this comment.
It's not, but the existing documentation says it is. The 'fix' is in #1423
api/server-server/keys_query.yaml
Outdated
| paths: | ||
| "/query/{serverName}/{keyId}": | ||
| get: | ||
| summary: Retreive a server key |
api/server-server/keys_query.yaml
Outdated
| "/query/{serverName}/{keyId}": | ||
| get: | ||
| summary: Retreive a server key | ||
| description: Retreive a server key |
There was a problem hiding this comment.
[also as per https://github.com/matrix-org/matrix-doc/blob/master/meta/documentation_style.rst#openapi this is meant to be a long-form description; however I'm happy if you want to punt that for now]
There was a problem hiding this comment.
The longer form descriptions are punted to a later PR which actually attempts to improve the documentation. The plan is to convert things to swagger then improve to make the diff a little bit more clear.
api/server-server/keys_query.yaml
Outdated
| $ref: "definitions/keys_query_response.yaml" | ||
| "/query": | ||
| post: | ||
| summary: Retreive a server key |
api/server-server/keys_query.yaml
Outdated
| "/query": | ||
| post: | ||
| summary: Retreive a server key | ||
| description: Retreive a server key |
api/server-server/keys_query.yaml
Outdated
| get: | ||
| summary: Retreive a server key | ||
| description: Retreive a server key | ||
| operationId: getQueryKeys |
There was a problem hiding this comment.
this is a bit of a funny name for it.
Maybe perspectivesKeyQuery and bulkPerspectivesKeyQuery ?
A later PR will improve the section. The goal here is to convert the code block to swagger.
Rendered: https://matrix.org/speculator/spec/1405/server_server/unstable.html#version-2