From 99e2ff4927b56db927d52e82ff802b38f6fa8407 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 19 Sep 2023 19:26:07 +0200 Subject: [PATCH] Replace all mentions of Swagger by OpenAPI (#1633) 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 | 14 ++--- .../internal/newsfragments/1633.clarification | 1 + data/api/client-server/keys.yaml | 2 +- .../partials/json-schema/resolve-allof.html | 2 +- layouts/partials/openapi/render-api.html | 2 +- .../partials/openapi/render-operation.html | 2 +- .../partials/openapi/render-parameters.html | 2 +- layouts/partials/openapi/render-request.html | 4 +- .../partials/openapi/render-responses.html | 2 +- layouts/shortcodes/http-api.html | 4 +- openapi_extensions.md | 55 ++----------------- ...er-sources.py => check-openapi-sources.py} | 10 ++-- scripts/{dump-swagger.py => dump-openapi.py} | 9 ++- ...-http-server.py => openapi-http-server.py} | 10 ++-- ...gger-preview.html => openapi-preview.html} | 0 17 files changed, 40 insertions(+), 87 deletions(-) create mode 100644 changelogs/internal/newsfragments/1633.clarification rename scripts/{check-swagger-sources.py => check-openapi-sources.py} (96%) rename scripts/{dump-swagger.py => dump-openapi.py} (95%) rename scripts/{swagger-http-server.py => openapi-http-server.py} (89%) rename scripts/{swagger-preview.html => openapi-preview.html} (100%) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index d836b100..4fc6a960 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 c1a34c50..09afe2d8 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 26d8f5c2..089bfe17 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,13 +87,13 @@ 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` -and finally `python ./scripts/dump-swagger.py` to generate it to `./scripts/swagger/api-docs.json`. To make use of the generated file, +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-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/changelogs/internal/newsfragments/1633.clarification b/changelogs/internal/newsfragments/1633.clarification new file mode 100644 index 00000000..64988279 --- /dev/null +++ b/changelogs/internal/newsfragments/1633.clarification @@ -0,0 +1 @@ +Replace all mentions of Swagger by OpenAPI. diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml index cb8a11db..594d141d 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 c7ffda15..db8fc13a 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 db10b98c..8af18e97 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 6486f39c..b3878664 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 0e643a25..925b0197 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 ce31943c..0771204b 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 37538b6e..c0ee5279 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 2668b1ab..a3b706db 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/openapi_extensions.md b/openapi_extensions.md index eba1121c..15b93adc 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 @@ -12,56 +12,9 @@ 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 -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. +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. ## Custom `x-addedInMatrixVersion` key diff --git a/scripts/check-swagger-sources.py b/scripts/check-openapi-sources.py similarity index 96% rename from scripts/check-swagger-sources.py rename to scripts/check-openapi-sources.py index 39e27f24..2fb8ad93 100755 --- a/scripts/check-swagger-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 @@ if __name__ == '__main__': # 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 @@ if __name__ == '__main__': 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-swagger.py b/scripts/dump-openapi.py similarity index 95% rename from scripts/dump-swagger.py rename to scripts/dump-openapi.py index ce97c4c3..1cc2279c 100755 --- a/scripts/dump-swagger.py +++ b/scripts/dump-openapi.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-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. -# 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-openapi.py - assemble the OpenAPI specs into a single JSON file" ) parser.add_argument( "--base-url", "-b", @@ -114,7 +113,7 @@ parser.add_argument( ) 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/swagger-http-server.py b/scripts/openapi-http-server.py similarity index 89% rename from scripts/swagger-http-server.py rename to scripts/openapi-http-server.py index 06d764aa..1865e6c8 100755 --- a/scripts/swagger-http-server.py +++ b/scripts/openapi-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 # @@ -41,13 +41,13 @@ if __name__ == '__main__': 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_dir) httpd = socketserver.TCPServer(("localhost", args.port), MyHTTPRequestHandler) 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