From 0ff882fb3b3467daf74aca2fb55c4a4f12614272 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 13 Jul 2018 11:41:51 +0100 Subject: [PATCH 1/7] Field definitions for protocol metadata --- api/application-service/definitions/protocol_metadata.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api/application-service/definitions/protocol_metadata.yaml b/api/application-service/definitions/protocol_metadata.yaml index 72264060..2b2c8f4e 100644 --- a/api/application-service/definitions/protocol_metadata.yaml +++ b/api/application-service/definitions/protocol_metadata.yaml @@ -13,6 +13,8 @@ # limitations under the License. type: object description: Dictionary of supported third party protocols. +additionalProperties: + $ref: protocol.yaml example: { "irc": { "user_fields": ["network", "nickname"], From 273acb277caa7020dbcea76e2707c45eca8670cd Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 13 Jul 2018 12:07:15 +0100 Subject: [PATCH 2/7] Change fields to use new extended query array syntax --- api/application-service/application_service.yaml | 4 ++-- api/client-server/third_party_lookup.yaml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml index b459e29f..138c75bd 100644 --- a/api/application-service/application_service.yaml +++ b/api/application-service/application_service.yaml @@ -270,7 +270,7 @@ paths: required: true x-example: irc - in: query - name: field1, field2... + name: fields... type: string description: |- One or more custom fields that are passed to the application @@ -321,7 +321,7 @@ paths: required: true x-example: irc - in: query - name: field1, field2... + name: field... type: string description: |- One or more custom fields that are passed to the application diff --git a/api/client-server/third_party_lookup.yaml b/api/client-server/third_party_lookup.yaml index 55d4c70a..226eec21 100644 --- a/api/client-server/third_party_lookup.yaml +++ b/api/client-server/third_party_lookup.yaml @@ -122,7 +122,7 @@ paths: required: true x-example: irc - in: query - name: field1, field2... + name: fields... type: string description: |- One or more custom fields that are passed to the AS to help identify the user. From 3e4962f21152e31bce6a3ff44bb0c65b11c89616 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 13 Jul 2018 12:25:48 +0100 Subject: [PATCH 3/7] Document standardized extensions to OpenAPI v2 --- api/openapi_extensions.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 api/openapi_extensions.rst diff --git a/api/openapi_extensions.rst b/api/openapi_extensions.rst new file mode 100644 index 00000000..75c48687 --- /dev/null +++ b/api/openapi_extensions.rst @@ -0,0 +1,23 @@ +OpenAPI Extensions +================== + +For some functionality that is not directly provided by the OpenAPI v2 +specification, some extensions have been added that are to be consistent +across the specification. The defined extensions are listed below. Extensions +should not break parsers, however if extra functionality is required, aware +parsers should be able to take advantage of the added syntax. + +Extensible Query Parameters +--------------------------- + +If a unknown amount of query parameters can be added to a request, the +``name`` should be in form of ``something...``, with the trailing ellipses +representing the possibility of more fields. + +Example: + +.. code-block:: + + - in: query + name: fields... + type: string \ No newline at end of file From 53137a3c5318c1a8e50a988e7c511302cf923590 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 23 Jul 2018 14:38:52 +0100 Subject: [PATCH 4/7] c/p bug, fix operationIds, move rst docs to md --- .../application_service.yaml | 2 +- api/application-service/definitions/user.yaml | 2 +- api/client-server/third_party_lookup.yaml | 9 +++++---- ...pi_extensions.rst => openapi_extensions.md} | 18 ++++++++---------- 4 files changed, 15 insertions(+), 16 deletions(-) rename api/{openapi_extensions.rst => openapi_extensions.md} (65%) diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml index 138c75bd..6f2eed16 100644 --- a/api/application-service/application_service.yaml +++ b/api/application-service/application_service.yaml @@ -214,7 +214,7 @@ paths: This API is called by the homeserver when it wants to present clients with specific information about the various third party networks that an application service supports. - operationId: queryMetadata + operationId: getProtocolMetadata parameters: - in: path name: protocol diff --git a/api/application-service/definitions/user.yaml b/api/application-service/definitions/user.yaml index 5f8d0460..a7b2287e 100644 --- a/api/application-service/definitions/user.yaml +++ b/api/application-service/definitions/user.yaml @@ -27,5 +27,5 @@ properties: type: object example: "user": "jim" -title: Location +title: User type: object \ No newline at end of file diff --git a/api/client-server/third_party_lookup.yaml b/api/client-server/third_party_lookup.yaml index 226eec21..ee14a137 100644 --- a/api/client-server/third_party_lookup.yaml +++ b/api/client-server/third_party_lookup.yaml @@ -34,7 +34,7 @@ paths: Fetches the overall metadata about protocols supported by the homeserver. Includes both the available protocols and all fields required for queries against each protocol. - operationId: queryMetadata + operationId: getProtocols responses: 200: description: The protocols supported by the homeserver. @@ -45,7 +45,7 @@ paths: summary: Retrieve metadata about a specific protocol that the homeserver supports. description: |- Fetches the metadata from the homeserver about a particular third party protocol. - operationId: queryMetadata + operationId: getProtocolMetadata parameters: - in: path name: protocol @@ -122,8 +122,9 @@ paths: required: true x-example: irc - in: query - name: fields... - type: string + name: fields + explode: true + type: object description: |- One or more custom fields that are passed to the AS to help identify the user. responses: diff --git a/api/openapi_extensions.rst b/api/openapi_extensions.md similarity index 65% rename from api/openapi_extensions.rst rename to api/openapi_extensions.md index 75c48687..4a01c477 100644 --- a/api/openapi_extensions.rst +++ b/api/openapi_extensions.md @@ -1,5 +1,4 @@ -OpenAPI Extensions -================== +# OpenAPI Extensions For some functionality that is not directly provided by the OpenAPI v2 specification, some extensions have been added that are to be consistent @@ -7,17 +6,16 @@ across the specification. The defined extensions are listed below. Extensions should not break parsers, however if extra functionality is required, aware parsers should be able to take advantage of the added syntax. -Extensible Query Parameters ---------------------------- +## Extensible Query Parameters -If a unknown amount of query parameters can be added to a request, the -``name`` should be in form of ``something...``, with the trailing ellipses -representing the possibility of more fields. +If a unknown amount of query parameters can be added to a request, the `name` +must be `fields...`, with the trailing ellipses representing the possibility +of more fields. Example: -.. code-block:: - +``` - in: query name: fields... - type: string \ No newline at end of file + type: string +``` \ No newline at end of file From d785ac78a355c85f68c82e3ff5e558378d2d1bc0 Mon Sep 17 00:00:00 2001 From: user Date: Mon, 30 Jul 2018 11:01:27 +0100 Subject: [PATCH 5/7] Remove explode and replace with TODO, require auth on CS --- api/client-server/third_party_lookup.yaml | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/api/client-server/third_party_lookup.yaml b/api/client-server/third_party_lookup.yaml index ee14a137..293a105b 100644 --- a/api/client-server/third_party_lookup.yaml +++ b/api/client-server/third_party_lookup.yaml @@ -35,6 +35,8 @@ paths: homeserver. Includes both the available protocols and all fields required for queries against each protocol. operationId: getProtocols + security: + - accessToken: [] responses: 200: description: The protocols supported by the homeserver. @@ -46,6 +48,8 @@ paths: description: |- Fetches the metadata from the homeserver about a particular third party protocol. operationId: getProtocolMetadata + security: + - accessToken: [] parameters: - in: path name: protocol @@ -80,6 +84,8 @@ paths: identifier. It should attempt to canonicalise the identifier as much as reasonably possible given the network type. operationId: queryLocationByProtocol + security: + - accessToken: [] parameters: - in: path name: protocol @@ -113,6 +119,8 @@ paths: Retrieve a Matrix User ID linked to a user on the third party service, given a set of user parameters. operationId: queryUserByProtocol + security: + - accessToken: [] parameters: - in: path name: protocol @@ -121,10 +129,10 @@ paths: The name of the protocol. required: true x-example: irc + # TODO: Change to 'explode' after OpenAPI/Swagger v3 update - in: query - name: fields - explode: true - type: object + name: field1, field2... + type: string description: |- One or more custom fields that are passed to the AS to help identify the user. responses: @@ -147,6 +155,8 @@ paths: Retreive an array of third party network locations from a Matrix room alias. operationId: queryLocationByAlias + security: + - accessToken: [] parameters: - in: query name: alias @@ -173,6 +183,8 @@ paths: description: |- Retreive an array of third party users from a Matrix User ID. operationId: queryUserByID + security: + - accessToken: [] parameters: - in: query name: userid @@ -192,4 +204,4 @@ paths: "errcode": "M_NOT_FOUND" } schema: - $ref: definitions/errors/error.yaml \ No newline at end of file + $ref: definitions/errors/error.yaml From a2e2ced03b1754ca71d69def19eb03e2deeb9766 Mon Sep 17 00:00:00 2001 From: user Date: Mon, 30 Jul 2018 11:09:13 +0100 Subject: [PATCH 6/7] Add reverse-lookup examples. --- api/client-server/third_party_lookup.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api/client-server/third_party_lookup.yaml b/api/client-server/third_party_lookup.yaml index 293a105b..55b34a81 100644 --- a/api/client-server/third_party_lookup.yaml +++ b/api/client-server/third_party_lookup.yaml @@ -163,6 +163,7 @@ paths: type: string description: The Matrix room alias to look up. required: true + x-example: "#matrix:matrix.org" responses: 200: description: |- @@ -191,6 +192,7 @@ paths: type: string description: The Matrix User ID to look up. required: true + x-example: "@bob:matrix.org" responses: 200: description: |- From 5f8967c0742faa108f994771e2ecc0b0b42854da Mon Sep 17 00:00:00 2001 From: user Date: Mon, 30 Jul 2018 19:19:35 +0100 Subject: [PATCH 7/7] Move TODO. field1, field2... -> fields... --- api/application-service/application_service.yaml | 4 ++-- api/client-server/third_party_lookup.yaml | 3 +-- api/openapi_extensions.md | 4 +++- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml index 6f2eed16..42c0c0cf 100644 --- a/api/application-service/application_service.yaml +++ b/api/application-service/application_service.yaml @@ -321,7 +321,7 @@ paths: required: true x-example: irc - in: query - name: field... + name: fields... type: string description: |- One or more custom fields that are passed to the application @@ -446,4 +446,4 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: - $ref: ../client-server/definitions/errors/error.yaml \ No newline at end of file + $ref: ../client-server/definitions/errors/error.yaml diff --git a/api/client-server/third_party_lookup.yaml b/api/client-server/third_party_lookup.yaml index 55b34a81..cba9ce22 100644 --- a/api/client-server/third_party_lookup.yaml +++ b/api/client-server/third_party_lookup.yaml @@ -129,9 +129,8 @@ paths: The name of the protocol. required: true x-example: irc - # TODO: Change to 'explode' after OpenAPI/Swagger v3 update - in: query - name: field1, field2... + name: fields... type: string description: |- One or more custom fields that are passed to the AS to help identify the user. diff --git a/api/openapi_extensions.md b/api/openapi_extensions.md index 4a01c477..9f4745fd 100644 --- a/api/openapi_extensions.md +++ b/api/openapi_extensions.md @@ -8,6 +8,8 @@ parsers should be able to take advantage of the added syntax. ## Extensible Query Parameters + + If a unknown amount of query parameters can be added to a request, the `name` must be `fields...`, with the trailing ellipses representing the possibility of more fields. @@ -18,4 +20,4 @@ Example: - in: query name: fields... type: string -``` \ No newline at end of file +```