From de9cf76a5729658816ed4e767ffce20e45e6c344 Mon Sep 17 00:00:00 2001 From: Alexandre Franke Date: Wed, 2 Feb 2022 16:51:07 +0100 Subject: [PATCH] Dump additional apis (#3684) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * ✨ Allow JSON generation for all API Signed-off-by: Alexandre Franke * 👷 Export AS API JSON Signed-off-by: Alexandre Franke * ✨ Handle missing security definitions Signed-off-by: Alexandre Franke * 👷 Export Push Gateway API JSON Signed-off-by: Alexandre Franke * 🎨 Improve identation Signed-off-by: Alexandre Franke * 🐛 Fix successive reference handling Fixes #3689 Signed-off-by: Alexandre Franke * 👷 Export Server-Server API JSON Signed-off-by: Alexandre Franke * 📝 Remove obsolete comment Signed-off-by: Alexandre Franke * 🐛 Make properties objects, as they MUST be Signed-off-by: Alexandre Franke * Revert "👷 Export Server-Server API JSON" This reverts commit 061f91c2cbcb6dff35c74177226da106826b4214. Co-authored-by: Alexandre Franke --- .github/workflows/main.yml | 11 +++ .../definitions/send_join_response.yaml | 4 +- .../definitions/single_pdu_transaction.yaml | 2 +- .../definitions/transaction.yaml | 2 +- .../unlimited_pdu_transaction.yaml | 2 +- data/api/server-server/event_auth.yaml | 2 +- data/api/server-server/events.yaml | 4 +- data/api/server-server/transactions.yaml | 2 +- scripts/dump-swagger.py | 69 +++++++++++++------ 9 files changed, 67 insertions(+), 31 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 778d3dbb..6ba90cb8 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -26,7 +26,9 @@ jobs: - name: "🔎 Run validator" working-directory: "./scripts" run: | + node validator.js -s "../data/api/application-service" node validator.js -s "../data/api/client-server" + node validator.js -s "../data/api/push-gateway" check-examples: name: "🔎 Check Event schema examples" @@ -76,7 +78,16 @@ jobs: # The output path matches the final deployment path at spec.matrix.org scripts/dump-swagger.py \ --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \ + --api application-service \ + -o spec/application-service-api/api.json + scripts/dump-swagger.py \ + --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \ + --api client-server \ -o spec/client-server-api/api.json + scripts/dump-swagger.py \ + --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \ + --api push-gateway \ + -o spec/push-gateway-api/api.json tar -czf openapi.tar.gz spec - name: "📤 Artifact upload" uses: actions/upload-artifact@v2 diff --git a/data/api/server-server/definitions/send_join_response.yaml b/data/api/server-server/definitions/send_join_response.yaml index 744324ba..12b020a2 100644 --- a/data/api/server-server/definitions/send_join_response.yaml +++ b/data/api/server-server/definitions/send_join_response.yaml @@ -34,7 +34,7 @@ properties: on the room version - check the [room version specification](/rooms) for precise event formats. schema: type: object - properties: [] + properties: {} example: $ref: "../examples/minimal_pdu.json" state: @@ -52,7 +52,7 @@ properties: on the room version - check the [room version specification](/rooms) for precise event formats. schema: type: object - properties: [] + properties: {} example: $ref: "../examples/minimal_pdu.json" event: diff --git a/data/api/server-server/definitions/single_pdu_transaction.yaml b/data/api/server-server/definitions/single_pdu_transaction.yaml index cb6750da..74b9744d 100644 --- a/data/api/server-server/definitions/single_pdu_transaction.yaml +++ b/data/api/server-server/definitions/single_pdu_transaction.yaml @@ -26,7 +26,7 @@ properties: description: |- The [PDUs](/server-server-api/#pdus) contained in the transaction. The event format varies depending on the room version - check the [room version specification](/rooms) for precise event formats. - properties: [] + properties: {} example: $ref: "../examples/minimal_pdu.json" required: ['origin', 'origin_server_ts', 'pdus'] diff --git a/data/api/server-server/definitions/transaction.yaml b/data/api/server-server/definitions/transaction.yaml index 1e33ef5c..e20204e0 100644 --- a/data/api/server-server/definitions/transaction.yaml +++ b/data/api/server-server/definitions/transaction.yaml @@ -41,7 +41,7 @@ properties: description: |- The [PDUs](/server-server-api/#pdus) contained in the transaction. The event format varies depending on the room version - check the [room version specification](/rooms) for precise event formats. - properties: [] + properties: {} example: $ref: "../examples/minimal_pdu.json" required: ['origin', 'origin_server_ts', 'pdus'] diff --git a/data/api/server-server/definitions/unlimited_pdu_transaction.yaml b/data/api/server-server/definitions/unlimited_pdu_transaction.yaml index 6e777671..003daee5 100644 --- a/data/api/server-server/definitions/unlimited_pdu_transaction.yaml +++ b/data/api/server-server/definitions/unlimited_pdu_transaction.yaml @@ -27,7 +27,7 @@ properties: description: |- The [PDUs](/server-server-api/#pdus) contained in the transaction. The event format varies depending on the room version - check the [room version specification](/rooms) for precise event formats. - properties: [] + properties: {} example: $ref: "../examples/minimal_pdu.json" required: ['origin', 'origin_server_ts', 'pdus'] diff --git a/data/api/server-server/event_auth.yaml b/data/api/server-server/event_auth.yaml index 8a2d47bf..ae4db262 100644 --- a/data/api/server-server/event_auth.yaml +++ b/data/api/server-server/event_auth.yaml @@ -64,7 +64,7 @@ paths: items: type: object title: PDU - properties: [] + properties: {} example: $ref: "examples/minimal_pdu.json" required: ['auth_chain'] diff --git a/data/api/server-server/events.yaml b/data/api/server-server/events.yaml index 823c6da6..4eef23b6 100644 --- a/data/api/server-server/events.yaml +++ b/data/api/server-server/events.yaml @@ -69,7 +69,7 @@ paths: The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format varies depending on the room version - check the [room version specification](/rooms) for precise event formats. - properties: [] + properties: {} example: $ref: "examples/minimal_pdu.json" pdus: @@ -85,7 +85,7 @@ paths: The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending on the room version - check the [room version specification](/rooms) for precise event formats. - properties: [] + properties: {} example: $ref: "examples/minimal_pdu.json" required: ['auth_chain', 'pdus'] diff --git a/data/api/server-server/transactions.yaml b/data/api/server-server/transactions.yaml index 46dd17af..cb801ee8 100644 --- a/data/api/server-server/transactions.yaml +++ b/data/api/server-server/transactions.yaml @@ -69,7 +69,7 @@ paths: $ref: "definitions/edu.yaml" example: { "$ref": "examples/transaction.json", - "edus": [{"$ref": "edu.json"}] # Relative to the examples directory + "edus": [{"$ref": "examples/edu.json"}] } responses: 200: diff --git a/scripts/dump-swagger.py b/scripts/dump-swagger.py index bbd4035e..e536ea85 100755 --- a/scripts/dump-swagger.py +++ b/scripts/dump-swagger.py @@ -37,11 +37,18 @@ def resolve_references(path, schema): # do $ref first if '$ref' in schema: value = schema['$ref'] + previous_path = path path = os.path.join(os.path.dirname(path), value) - with open(path, encoding="utf-8") as f: - ref = yaml.safe_load(f) - result = resolve_references(path, ref) - del schema['$ref'] + try: + with open(path, encoding="utf-8") as f: + ref = yaml.safe_load(f) + result = resolve_references(path, ref) + del schema['$ref'] + path = previous_path + except FileNotFoundError: + print("Resolving {}".format(schema)) + print("File not found: {}".format(path)) + result = {} else: result = {} @@ -87,11 +94,24 @@ parser.add_argument( %(default)s""", ) parser.add_argument( - "--client_release", "-c", metavar="LABEL", + "--spec-release", "-r", metavar="LABEL", default="unstable", - help="""The client-server release version to generate for. Default: + help="""The spec release version to generate for. Default: %(default)s""", ) +available_apis = { + "client-server": "Matrix Client-Server API", + "server-server": "Matrix Server-Server API", + "application-service": "Matrix Application Service API", + "identity": "Matrix Identity Service API", + "push-gateway": "Matrix Push Gateway API", +} +parser.add_argument( + "--api", + default="client-server", + choices=available_apis, + help="""The API to generate for. Default: %(default)s""", +) parser.add_argument( "-o", "--output", default=os.path.join(scripts_dir, "swagger", "api-docs.json"), @@ -100,7 +120,8 @@ parser.add_argument( args = parser.parse_args() output_file = os.path.abspath(args.output) -release_label = args.client_release +release_label = args.spec_release +selected_api = args.api major_version = release_label match = re.match("^(r\d+)(\.\d+)*$", major_version) @@ -119,18 +140,20 @@ output = { # The servers value will be picked up by RapiDoc to provide a way # to switch API servers. Useful when one wants to test compliance # of their server with the API. - "servers": [{ - "url": "https://{homeserver_address}/", - "variables": { - "homeserver_address": { - "default": "matrix-client.matrix.org", - "description": "The base URL for your homeserver", - } + "servers": [ + { + "url": "https://{homeserver_address}/", + "variables": { + "homeserver_address": { + "default": "matrix-client.matrix.org", + "description": "The base URL for your homeserver", + } + }, } - }], + ], "schemes": ["https"], "info": { - "title": "Matrix Client-Server API", + "title": available_apis[selected_api], "version": release_label, }, "securityDefinitions": {}, @@ -138,15 +161,17 @@ output = { "swagger": "2.0", } -cs_api_dir = os.path.join(api_dir, 'client-server') -with open(os.path.join(cs_api_dir, 'definitions', - 'security.yaml')) as f: - output['securityDefinitions'] = yaml.safe_load(f) +selected_api_dir = os.path.join(api_dir, selected_api) +try: + with open(os.path.join(selected_api_dir, 'definitions', 'security.yaml')) as f: + output['securityDefinitions'] = yaml.safe_load(f) +except FileNotFoundError: + print("No security definitions available for this API") -for filename in os.listdir(cs_api_dir): +for filename in os.listdir(selected_api_dir): if not filename.endswith(".yaml"): continue - filepath = os.path.join(cs_api_dir, filename) + filepath = os.path.join(selected_api_dir, filename) print("Reading swagger API: %s" % filepath) with open(filepath, "r") as f: