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] 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 26d8f5c2..b78841ef 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 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/scripts/dump-swagger.py b/scripts/dump-swagger.py index ce97c4c3..b9b3b6a3 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 06d764aa..4f43daf8 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 #