From bae676da7012b4657b8091259d7b3b87f14c84da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 12 Sep 2023 12:15:04 +0200 Subject: [PATCH 1/6] Update OpenAPI Extensions for OpenAPI 3.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- openapi_extensions.md | 53 +++---------------------------------------- 1 file changed, 3 insertions(+), 50 deletions(-) diff --git a/openapi_extensions.md b/openapi_extensions.md index eba1121cf..9e833f185 100644 --- a/openapi_extensions.md +++ b/openapi_extensions.md @@ -1,6 +1,6 @@ # OpenAPI Extensions -For some functionality that is not directly provided by the OpenAPI v2 +For some functionality that is not directly provided by the OpenAPI v3.1 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 @@ -13,55 +13,8 @@ files. Each of these files is self-contained valid OpenAPI. There is no single root file in the source tree as OpenAPI requires; this file can be generated by `dump-swagger.py`. The script does not convert -the extensions described further in this document (`oneOf` and parameter -exploding) so there can be minor interoperability issues with tooling that -expects compliant Swagger. - -## 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. - -Example: - -``` - - in: query - name: fields... - type: string -``` - -## Using oneOf to provide type alternatives - - - -`oneOf` (available in JSON Schema and Swagger/OpenAPI v3 but not in v2) -is used in cases when a simpler type specification as a list of types -doesn't work, as in the following example: -``` - properties: - old: # compliant with old Swagger - type: - - string - - object # Cannot specify a schema here - new: # uses oneOf extension - oneOf: - - type: string - - type: object - title: CustomSchemaForTheWin - properties: - ... -``` - -## OpenAPI 3's "2xx" format for response codes - - - -In some cases, the schema will have HTTP response code definitions like -`2xx`, `3xx`, and `4xx`. These indicate that a response code within those -ranges (`2xx` = `200` to `299`) is valid for the schema. +the extensions described further in this document so there can be minor +interoperability issues with tooling that expects compliant OpenAPI. ## Custom `x-addedInMatrixVersion` key From ec4db7f8ee8c524ee29ade51759bc5f86d4b38be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 12 Sep 2023 12:30:50 +0200 Subject: [PATCH 2/6] Remove mentions of Swagger in docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- README.md | 6 +++--- data/api/client-server/keys.yaml | 2 +- layouts/partials/json-schema/resolve-allof.html | 2 +- layouts/partials/openapi/render-api.html | 2 +- layouts/partials/openapi/render-operation.html | 2 +- layouts/partials/openapi/render-parameters.html | 2 +- layouts/partials/openapi/render-request.html | 4 ++-- layouts/partials/openapi/render-responses.html | 2 +- layouts/shortcodes/http-api.html | 4 ++-- scripts/dump-swagger.py | 7 +++---- scripts/swagger-http-server.py | 4 ++-- 11 files changed, 18 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 26d8f5c24..b78841ef6 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ The Matrix spec is compiled with [Hugo](https://gohugo.io/) (a static site gener * `/data`: this can contain TOML, YAML, or JSON files. Files kept here are directly available to template code as [data objects](https://gohugo.io/templates/data-templates/), so templates don't need to load them from a file and - parse them. This is also where our Swagger/OpenAPI definitions and schemas are. + parse them. This is also where our OpenAPI definitions and schemas are. * `/layouts`: this contains [Hugo templates](https://gohugo.io/templates/). Some templates define the overall layout of a page: for example, whether it has header, footer, sidebar, and so on. @@ -52,7 +52,7 @@ Additionally, the following directories may be of interest: * `/data-definitions`: Bits of structured data consumable by Matrix implementations. * `/meta`: Documentation relating to the spec's processes that are otherwise untracked (release instructions, etc). * `/scripts`: Various scripts for generating the spec and validating its contents. -* `/packages`: Various packages for shipping spec files like OpenAPI/swagger bindings and data definitions. +* `/packages`: Various packages for shipping spec files like OpenAPI bindings and data definitions. ## Authoring changes to the spec @@ -87,7 +87,7 @@ steps for authoring changes to the specification and instead of `hugo serve` run spec to `/spec`. If you'd like to serve the spec off a path instead of a domain root (eg: `/unstable`), add `--baseURL "/unstable"` to the `hugo -d "spec"` command. -For building the swagger definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt` +For building the OpenAPI definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt` and finally `python ./scripts/dump-swagger.py` to generate it to `./scripts/swagger/api-docs.json`. To make use of the generated file, there are a number of options: diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml index cb8a11dbb..594d141d3 100644 --- a/data/api/client-server/keys.yaml +++ b/data/api/client-server/keys.yaml @@ -40,7 +40,7 @@ paths: one_time_keys: # $ref: "definitions/one_time_keys.yaml" # XXX: We can't define an actual object here, so we have to hope - # that people will look at the swagger source or can figure it out + # that people will look at the OpenAPI source or can figure it out # from the other endpoints/example. type: object title: OneTimeKeys diff --git a/layouts/partials/json-schema/resolve-allof.html b/layouts/partials/json-schema/resolve-allof.html index c7ffda155..db8fc13a4 100644 --- a/layouts/partials/json-schema/resolve-allof.html +++ b/layouts/partials/json-schema/resolve-allof.html @@ -1,6 +1,6 @@ {{/* - Resolves the `allOf` keyword (https://swagger.io/specification/v2/#composition-and-inheritance-polymorphism), + Resolves the `allOf` keyword (https://spec.openapis.org/oas/v3.1.0#composition-and-inheritance-polymorphism), given a JSON schema object. `allOf` is used to support a kind of inheritance for JSON schema objects. diff --git a/layouts/partials/openapi/render-api.html b/layouts/partials/openapi/render-api.html index db10b98c0..8af18e970 100644 --- a/layouts/partials/openapi/render-api.html +++ b/layouts/partials/openapi/render-api.html @@ -2,7 +2,7 @@ Render an HTTP API, given: - * `api_data`: the OpenAPI/Swagger data + * `api_data`: the OpenAPI data * `base_url`: the base URL: that is, the part we glue onto the front of each value in `paths` to get a complete URL. * `path`: the directory under /data where we found this API definition. diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index 6486f39c7..b3878664f 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -4,7 +4,7 @@ * `method`: the method, e.g. GET, PUT * `endpoint`: the endpoint - * `operation_data`: the OpenAPI/Swagger data for the operation + * `operation_data`: the OpenAPI data for the operation * `path`: the path where this definition was found, to enable us to resolve "$ref" This template renders the operation as a `
` containing: diff --git a/layouts/partials/openapi/render-parameters.html b/layouts/partials/openapi/render-parameters.html index 0e643a259..925b01979 100644 --- a/layouts/partials/openapi/render-parameters.html +++ b/layouts/partials/openapi/render-parameters.html @@ -2,7 +2,7 @@ Render the parameters of a given type, given: - * `parameters`: OpenAPI/Swagger data specifying the parameters + * `parameters`: OpenAPI data specifying the parameters * `type`: the type of parameters to render: "header, ""path", "query" * `caption`: caption to use for the table diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index ce31943c6..0771204b3 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -2,8 +2,8 @@ Render the request part of a single HTTP API operation, given: - * `parameters`: OpenAPI/Swagger data specifying the parameters - * `request_body`: OpenAPI/Swagger data specifying the request body + * `parameters`: OpenAPI data specifying the parameters + * `request_body`: OpenAPI data specifying the request body * `path`: the path where this definition was found, to enable us to resolve "$ref" * `anchor_base`: a prefix to add to the HTML anchors generated for each object diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index 37538b6e4..c0ee52795 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -2,7 +2,7 @@ Render the response part of a single HTTP API operation, given: - * `responses`: OpenAPI/Swagger data specifying the responses + * `responses`: OpenAPI data specifying the responses * `path`: the path where this definition was found, to enable us to resolve "$ref" * `anchor_base`: a prefix to add to the HTML anchors generated for each object diff --git a/layouts/shortcodes/http-api.html b/layouts/shortcodes/http-api.html index 2668b1abc..a3b706db6 100644 --- a/layouts/shortcodes/http-api.html +++ b/layouts/shortcodes/http-api.html @@ -1,12 +1,12 @@ {{/* - This template is used to render an HTTP API, given an OpenAPI/Swagger definition. + This template is used to render an HTTP API, given an OpenAPI definition. It expects to be passed two parameters: * a `spec` parameter identifying the spec, which must be the name of a directory under /data/api - * an `api` parameter, identifying an OpenAPI/Swagger definition, + * an `api` parameter, identifying an OpenAPI definition, which is the name of a schema file under "data/api/$spec". The file extension is omitted. For example: diff --git a/scripts/dump-swagger.py b/scripts/dump-swagger.py index ce97c4c3c..b9b3b6a35 100755 --- a/scripts/dump-swagger.py +++ b/scripts/dump-swagger.py @@ -1,9 +1,8 @@ #!/usr/bin/env python3 -# dump-swagger reads all of the swagger API docs used in spec generation and -# outputs a JSON file which merges them all, for use as input to a swagger UI +# dump-swagger reads all of the OpenAPI docs used in spec generation and +# outputs a JSON file which merges them all, for use as input to an OpenAPI # viewer. -# See https://github.com/swagger-api/swagger-ui for details of swagger-ui. # Copyright 2016 OpenMarket Ltd # @@ -85,7 +84,7 @@ def edit_links(node, base_url): edit_links(item, base_url) parser = argparse.ArgumentParser( - "dump-swagger.py - assemble the Swagger specs into a single JSON file" + "dump-swagger.py - assemble the OpenAPI specs into a single JSON file" ) parser.add_argument( "--base-url", "-b", diff --git a/scripts/swagger-http-server.py b/scripts/swagger-http-server.py index 06d764aa0..4f43daf89 100755 --- a/scripts/swagger-http-server.py +++ b/scripts/swagger-http-server.py @@ -1,7 +1,7 @@ #!/usr/bin/env python -# Runs an HTTP server on localhost:8000 which will serve the generated swagger -# JSON so that it can be viewed in an online swagger UI. +# Runs an HTTP server on localhost:8000 which will serve the generated OpenAPI +# JSON so that it can be viewed in an online OpenAPI viewer. # Copyright 2016 OpenMarket Ltd # From 217fbbeab11645bfecfc1c41a48dc00a7a7da054 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 12 Sep 2023 12:36:58 +0200 Subject: [PATCH 3/6] Rename scripts using openapi instead of swagger MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .github/workflows/main.yml | 6 +++--- .gitignore | 2 +- README.md | 8 ++++---- openapi_extensions.md | 2 +- ...{check-swagger-sources.py => check-openapi-sources.py} | 0 scripts/{dump-swagger.py => dump-openapi.py} | 0 .../{swagger-http-server.py => openapi-http-server.py} | 0 scripts/{swagger-preview.html => openapi-preview.html} | 0 8 files changed, 9 insertions(+), 9 deletions(-) rename scripts/{check-swagger-sources.py => check-openapi-sources.py} (100%) rename scripts/{dump-swagger.py => dump-openapi.py} (100%) rename scripts/{swagger-http-server.py => openapi-http-server.py} (100%) rename scripts/{swagger-preview.html => openapi-preview.html} (100%) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index d836b100a..4fc6a9601 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -92,17 +92,17 @@ jobs: export RELEASE="unstable" fi # The output path matches the final deployment path at spec.matrix.org - scripts/dump-swagger.py \ + scripts/dump-openapi.py \ --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \ --api application-service \ -r "$RELEASE" \ -o spec/application-service-api/api.json - scripts/dump-swagger.py \ + scripts/dump-openapi.py \ --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \ --api client-server \ -r "$RELEASE" \ -o spec/client-server-api/api.json - scripts/dump-swagger.py \ + scripts/dump-openapi.py \ --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \ --api push-gateway \ -r "$RELEASE" \ diff --git a/.gitignore b/.gitignore index c1a34c508..09afe2d89 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,7 @@ node_modules /data/msc /env* /resources -/scripts/swagger +/scripts/openapi /scripts/tmp /hugo-config.toml /public diff --git a/README.md b/README.md index b78841ef6..089bfe17b 100644 --- a/README.md +++ b/README.md @@ -88,12 +88,12 @@ spec to `/spec`. If you'd like to serve the spec off a path instead of a domain to the `hugo -d "spec"` command. For building the OpenAPI definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt` -and finally `python ./scripts/dump-swagger.py` to generate it to `./scripts/swagger/api-docs.json`. To make use of the generated file, +and finally `python ./scripts/dump-openapi.py` to generate it to `./scripts/openapi/api-docs.json`. To make use of the generated file, there are a number of options: -* You can open `./scripts/swagger-preview.html` in your browser, and then open the file by clicking on `Local JSON File`. -* You can run a local HTTP server by running `./scripts/swagger-http-server.py`, and then view the documentation by - opening `./scripts/swagger-preview.html` in your browser. +* You can open `./scripts/openapi-preview.html` in your browser, and then open the file by clicking on `Local JSON File`. +* You can run a local HTTP server by running `./scripts/openapi-http-server.py`, and then view the documentation by + opening `./scripts/openapi-preview.html` in your browser. ## Issue tracking diff --git a/openapi_extensions.md b/openapi_extensions.md index 9e833f185..15b93adc8 100644 --- a/openapi_extensions.md +++ b/openapi_extensions.md @@ -12,7 +12,7 @@ To ease API design and management, the API definition is split across several files. Each of these files is self-contained valid OpenAPI. There is no single root file in the source tree as OpenAPI requires; this file -can be generated by `dump-swagger.py`. The script does not convert +can be generated by `dump-openapi.py`. The script does not convert the extensions described further in this document so there can be minor interoperability issues with tooling that expects compliant OpenAPI. diff --git a/scripts/check-swagger-sources.py b/scripts/check-openapi-sources.py similarity index 100% rename from scripts/check-swagger-sources.py rename to scripts/check-openapi-sources.py diff --git a/scripts/dump-swagger.py b/scripts/dump-openapi.py similarity index 100% rename from scripts/dump-swagger.py rename to scripts/dump-openapi.py diff --git a/scripts/swagger-http-server.py b/scripts/openapi-http-server.py similarity index 100% rename from scripts/swagger-http-server.py rename to scripts/openapi-http-server.py diff --git a/scripts/swagger-preview.html b/scripts/openapi-preview.html similarity index 100% rename from scripts/swagger-preview.html rename to scripts/openapi-preview.html From 2b30ff48ec106785fc14e12de04f13650cf0ed4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 12 Sep 2023 12:45:58 +0200 Subject: [PATCH 4/6] Add changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/internal/newsfragments/1633.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/internal/newsfragments/1633.clarification diff --git a/changelogs/internal/newsfragments/1633.clarification b/changelogs/internal/newsfragments/1633.clarification new file mode 100644 index 000000000..64988279f --- /dev/null +++ b/changelogs/internal/newsfragments/1633.clarification @@ -0,0 +1 @@ +Replace all mentions of Swagger by OpenAPI. From f70d54453a8439d92ebec10678b9be64984215f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 19 Sep 2023 16:51:32 +0200 Subject: [PATCH 5/6] More renaming MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- scripts/check-openapi-sources.py | 10 +++++----- scripts/dump-openapi.py | 6 +++--- scripts/openapi-http-server.py | 6 +++--- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/scripts/check-openapi-sources.py b/scripts/check-openapi-sources.py index 39e27f240..2fb8ad938 100755 --- a/scripts/check-openapi-sources.py +++ b/scripts/check-openapi-sources.py @@ -87,11 +87,11 @@ def check_response(filepath, request, code, response): ), e) -def check_swagger_file(filepath): +def check_openapi_file(filepath): with open(filepath) as f: - swagger = yaml.safe_load(f) + openapi = yaml.safe_load(f) - for path, path_api in swagger.get('paths', {}).items(): + for path, path_api in openapi.get('paths', {}).items(): for method, request_api in path_api.items(): request = "%s %s" % (method.upper(), path) @@ -169,7 +169,7 @@ def load_file(path): # Get the directory that this script is residing in script_directory = os.path.dirname(os.path.realpath(__file__)) - # Resolve the directory containing the swagger sources, + # Resolve the directory containing the OpenAPI sources, # relative to the script path source_files_directory = os.path.realpath(os.path.join(script_directory, "../data")) @@ -182,6 +182,6 @@ def load_file(path): path = os.path.join(root, filename) try: - check_swagger_file(path) + check_openapi_file(path) except Exception as e: raise ValueError("Error checking file %s" % (path,), e) diff --git a/scripts/dump-openapi.py b/scripts/dump-openapi.py index b9b3b6a35..1cc2279c7 100755 --- a/scripts/dump-openapi.py +++ b/scripts/dump-openapi.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 -# dump-swagger reads all of the OpenAPI docs used in spec generation and +# dump-openapi reads all of the OpenAPI docs used in spec generation and # outputs a JSON file which merges them all, for use as input to an OpenAPI # viewer. @@ -84,7 +84,7 @@ def edit_links(node, base_url): edit_links(item, base_url) parser = argparse.ArgumentParser( - "dump-swagger.py - assemble the OpenAPI specs into a single JSON file" + "dump-openapi.py - assemble the OpenAPI specs into a single JSON file" ) parser.add_argument( "--base-url", "-b", @@ -113,7 +113,7 @@ def edit_links(node, base_url): ) parser.add_argument( "-o", "--output", - default=os.path.join(scripts_dir, "swagger", "api-docs.json"), + default=os.path.join(scripts_dir, "openapi", "api-docs.json"), help="File to write the output to. Default: %(default)s" ) args = parser.parse_args() diff --git a/scripts/openapi-http-server.py b/scripts/openapi-http-server.py index 4f43daf89..307e7dbe8 100755 --- a/scripts/openapi-http-server.py +++ b/scripts/openapi-http-server.py @@ -41,13 +41,13 @@ def send_my_headers(self): help='TCP port to listen on (default: %(default)s)', ) parser.add_argument( - 'swagger_dir', nargs='?', - default=os.path.join(scripts_dir, 'swagger'), + 'openapi_dir', nargs='?', + default=os.path.join(scripts_dir, 'openapi'), help='directory to serve (default: %(default)s)', ) args = parser.parse_args() - os.chdir(args.swagger_dir) + os.chdir(args.openapi) httpd = socketserver.TCPServer(("localhost", args.port), MyHTTPRequestHandler) From d30de67caa13de35b4bf1aa73ae818f8ae22a1e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 19 Sep 2023 18:02:03 +0200 Subject: [PATCH 6/6] Fix dict field name MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- scripts/openapi-http-server.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/openapi-http-server.py b/scripts/openapi-http-server.py index 307e7dbe8..1865e6c8d 100755 --- a/scripts/openapi-http-server.py +++ b/scripts/openapi-http-server.py @@ -47,7 +47,7 @@ def send_my_headers(self): ) args = parser.parse_args() - os.chdir(args.openapi) + os.chdir(args.openapi_dir) httpd = socketserver.TCPServer(("localhost", args.port), MyHTTPRequestHandler)