From a69874ba08535870c669c50619fb62fac416ed17 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 14 Aug 2024 16:46:41 +0200 Subject: [PATCH] prettier yaml examples --- examples/v3.0/api-with-examples.yaml | 245 ++++++++++++++------------- examples/v3.0/callback-example.yaml | 8 +- examples/v3.0/link-example.yaml | 240 +++++++++++++------------- examples/v3.0/petstore-expanded.yaml | 32 ++-- examples/v3.0/petstore.yaml | 10 +- examples/v3.0/uspto.yaml | 59 +++---- examples/v3.1/non-oauth-scopes.yaml | 7 +- examples/v3.1/tictactoe.yaml | 8 +- examples/v3.1/webhook-example.yaml | 1 - 9 files changed, 309 insertions(+), 301 deletions(-) diff --git a/examples/v3.0/api-with-examples.yaml b/examples/v3.0/api-with-examples.yaml index 18726a5..62733df 100644 --- a/examples/v3.0/api-with-examples.yaml +++ b/examples/v3.0/api-with-examples.yaml @@ -8,163 +8,172 @@ paths: operationId: listVersionsv2 summary: List API versions responses: - '200': + "200": description: |- 200 response content: application/json: - examples: + examples: foo: value: { - "versions": [ - { + "versions": + [ + { "status": "CURRENT", "updated": "2011-01-21T11:33:21Z", "id": "v2.0", - "links": [ + "links": + [ { - "href": "http://127.0.0.1:8774/v2/", - "rel": "self" - } - ] - }, - { + "href": "http://127.0.0.1:8774/v2/", + "rel": "self", + }, + ], + }, + { "status": "EXPERIMENTAL", "updated": "2013-07-23T11:33:21Z", "id": "v3.0", - "links": [ + "links": + [ { - "href": "http://127.0.0.1:8774/v3/", - "rel": "self" - } - ] - } - ] + "href": "http://127.0.0.1:8774/v3/", + "rel": "self", + }, + ], + }, + ], } - '300': + "300": description: |- 300 response content: - application/json: - examples: + application/json: + examples: foo: value: | - { - "versions": [ - { - "status": "CURRENT", - "updated": "2011-01-21T11:33:21Z", - "id": "v2.0", - "links": [ - { - "href": "http://127.0.0.1:8774/v2/", - "rel": "self" - } - ] - }, - { - "status": "EXPERIMENTAL", - "updated": "2013-07-23T11:33:21Z", - "id": "v3.0", - "links": [ - { - "href": "http://127.0.0.1:8774/v3/", - "rel": "self" - } - ] - } - ] - } + { + "versions": [ + { + "status": "CURRENT", + "updated": "2011-01-21T11:33:21Z", + "id": "v2.0", + "links": [ + { + "href": "http://127.0.0.1:8774/v2/", + "rel": "self" + } + ] + }, + { + "status": "EXPERIMENTAL", + "updated": "2013-07-23T11:33:21Z", + "id": "v3.0", + "links": [ + { + "href": "http://127.0.0.1:8774/v3/", + "rel": "self" + } + ] + } + ] + } /v2: get: operationId: getVersionDetailsv2 summary: Show API version details responses: - '200': + "200": description: |- 200 response content: - application/json: + application/json: examples: foo: value: { - "version": { - "status": "CURRENT", - "updated": "2011-01-21T11:33:21Z", - "media-types": [ - { - "base": "application/xml", - "type": "application/vnd.openstack.compute+xml;version=2" - }, - { - "base": "application/json", - "type": "application/vnd.openstack.compute+json;version=2" - } - ], - "id": "v2.0", - "links": [ - { - "href": "http://127.0.0.1:8774/v2/", - "rel": "self" - }, - { - "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", - "type": "application/pdf", - "rel": "describedby" - }, - { - "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", - "type": "application/vnd.sun.wadl+xml", - "rel": "describedby" - }, - { - "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", - "type": "application/vnd.sun.wadl+xml", - "rel": "describedby" - } - ] - } + "version": + { + "status": "CURRENT", + "updated": "2011-01-21T11:33:21Z", + "media-types": + [ + { + "base": "application/xml", + "type": "application/vnd.openstack.compute+xml;version=2", + }, + { + "base": "application/json", + "type": "application/vnd.openstack.compute+json;version=2", + }, + ], + "id": "v2.0", + "links": + [ + { + "href": "http://127.0.0.1:8774/v2/", + "rel": "self", + }, + { + "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", + "type": "application/pdf", + "rel": "describedby", + }, + { + "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", + "type": "application/vnd.sun.wadl+xml", + "rel": "describedby", + }, + { + "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", + "type": "application/vnd.sun.wadl+xml", + "rel": "describedby", + }, + ], + }, } - '203': + "203": description: |- 203 response content: - application/json: + application/json: examples: foo: value: { - "version": { - "status": "CURRENT", - "updated": "2011-01-21T11:33:21Z", - "media-types": [ - { - "base": "application/xml", - "type": "application/vnd.openstack.compute+xml;version=2" - }, - { - "base": "application/json", - "type": "application/vnd.openstack.compute+json;version=2" - } - ], - "id": "v2.0", - "links": [ - { - "href": "http://23.253.228.211:8774/v2/", - "rel": "self" - }, - { - "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", - "type": "application/pdf", - "rel": "describedby" - }, - { - "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", - "type": "application/vnd.sun.wadl+xml", - "rel": "describedby" - } - ] - } + "version": + { + "status": "CURRENT", + "updated": "2011-01-21T11:33:21Z", + "media-types": + [ + { + "base": "application/xml", + "type": "application/vnd.openstack.compute+xml;version=2", + }, + { + "base": "application/json", + "type": "application/vnd.openstack.compute+json;version=2", + }, + ], + "id": "v2.0", + "links": + [ + { + "href": "http://23.253.228.211:8774/v2/", + "rel": "self", + }, + { + "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", + "type": "application/pdf", + "rel": "describedby", + }, + { + "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", + "type": "application/vnd.sun.wadl+xml", + "rel": "describedby", + }, + ], + }, } diff --git a/examples/v3.0/callback-example.yaml b/examples/v3.0/callback-example.yaml index 262b8df..0bd0f93 100644 --- a/examples/v3.0/callback-example.yaml +++ b/examples/v3.0/callback-example.yaml @@ -18,7 +18,7 @@ paths: format: uri example: https://tonys-server.com responses: - '201': + "201": description: subscription successfully created content: application/json: @@ -36,7 +36,7 @@ paths: onData: # when data is sent, it will be sent to the `callbackUrl` provided # when making the subscription PLUS the suffix `/data` - '{$request.query.callbackUrl}/data': + "{$request.query.callbackUrl}/data": post: requestBody: description: subscription payload @@ -51,11 +51,11 @@ paths: userData: type: string responses: - '202': + "202": description: | Your server implementation should return this HTTP status code if the data was received successfully - '204': + "204": description: | Your server should return this HTTP status code if no longer interested in further updates diff --git a/examples/v3.0/link-example.yaml b/examples/v3.0/link-example.yaml index 5837d70..8616f32 100644 --- a/examples/v3.0/link-example.yaml +++ b/examples/v3.0/link-example.yaml @@ -1,27 +1,27 @@ openapi: 3.0.0 -info: +info: title: Link Example version: 1.0.0 -paths: - /2.0/users/{username}: - get: +paths: + /2.0/users/{username}: + get: operationId: getUserByName - parameters: - - name: username - in: path - required: true - schema: - type: string - responses: - '200': + parameters: + - name: username + in: path + required: true + schema: + type: string + responses: + "200": description: The User content: application/json: - schema: - $ref: '#/components/schemas/user' + schema: + $ref: "#/components/schemas/user" links: userRepositories: - $ref: '#/components/links/UserRepositories' + $ref: "#/components/links/UserRepositories" /2.0/repositories/{username}: get: operationId: getRepositoriesByOwner @@ -32,21 +32,21 @@ paths: schema: type: string responses: - '200': + "200": description: repositories owned by the supplied user - content: + content: application/json: schema: type: array items: - $ref: '#/components/schemas/repository' + $ref: "#/components/schemas/repository" links: userRepository: - $ref: '#/components/links/UserRepository' - /2.0/repositories/{username}/{slug}: - get: + $ref: "#/components/links/UserRepository" + /2.0/repositories/{username}/{slug}: + get: operationId: getRepository - parameters: + parameters: - name: username in: path required: true @@ -57,97 +57,97 @@ paths: required: true schema: type: string - responses: - '200': + responses: + "200": description: The repository content: - application/json: - schema: - $ref: '#/components/schemas/repository' + application/json: + schema: + $ref: "#/components/schemas/repository" links: repositoryPullRequests: - $ref: '#/components/links/RepositoryPullRequests' - /2.0/repositories/{username}/{slug}/pullrequests: - get: + $ref: "#/components/links/RepositoryPullRequests" + /2.0/repositories/{username}/{slug}/pullrequests: + get: operationId: getPullRequestsByRepository - parameters: - - name: username - in: path - required: true - schema: - type: string - - name: slug - in: path - required: true - schema: - type: string - - name: state - in: query - schema: - type: string - enum: - - open - - merged - - declined - responses: - '200': + parameters: + - name: username + in: path + required: true + schema: + type: string + - name: slug + in: path + required: true + schema: + type: string + - name: state + in: query + schema: + type: string + enum: + - open + - merged + - declined + responses: + "200": description: an array of pull request objects content: - application/json: - schema: + application/json: + schema: type: array - items: - $ref: '#/components/schemas/pullrequest' - /2.0/repositories/{username}/{slug}/pullrequests/{pid}: - get: + items: + $ref: "#/components/schemas/pullrequest" + /2.0/repositories/{username}/{slug}/pullrequests/{pid}: + get: operationId: getPullRequestsById - parameters: - - name: username - in: path - required: true - schema: - type: string - - name: slug - in: path - required: true - schema: - type: string - - name: pid - in: path - required: true - schema: - type: string - responses: - '200': + parameters: + - name: username + in: path + required: true + schema: + type: string + - name: slug + in: path + required: true + schema: + type: string + - name: pid + in: path + required: true + schema: + type: string + responses: + "200": description: a pull request object content: - application/json: - schema: - $ref: '#/components/schemas/pullrequest' + application/json: + schema: + $ref: "#/components/schemas/pullrequest" links: pullRequestMerge: - $ref: '#/components/links/PullRequestMerge' - /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge: - post: + $ref: "#/components/links/PullRequestMerge" + /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge: + post: operationId: mergePullRequest - parameters: - - name: username - in: path - required: true - schema: - type: string - - name: slug - in: path - required: true - schema: - type: string - - name: pid - in: path - required: true - schema: - type: string - responses: - '204': + parameters: + - name: username + in: path + required: true + schema: + type: string + - name: slug + in: path + required: true + schema: + type: string + - name: pid + in: path + required: true + schema: + type: string + responses: + "204": description: the PR was successfully merged components: links: @@ -165,9 +165,9 @@ components: RepositoryPullRequests: # returns '#/components/schemas/pullrequest' operationId: getPullRequestsByRepository - parameters: - username: $response.body#/owner/username - slug: $response.body#/slug + parameters: + username: $response.body#/owner/username + slug: $response.body#/slug PullRequestMerge: # executes /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge operationId: mergePullRequest @@ -175,29 +175,29 @@ components: username: $response.body#/author/username slug: $response.body#/repository/slug pid: $response.body#/id - schemas: - user: + schemas: + user: type: object - properties: - username: + properties: + username: type: string - uuid: + uuid: type: string - repository: + repository: type: object - properties: - slug: + properties: + slug: type: string - owner: - $ref: '#/components/schemas/user' - pullrequest: + owner: + $ref: "#/components/schemas/user" + pullrequest: type: object - properties: - id: + properties: + id: type: integer - title: + title: type: string - repository: - $ref: '#/components/schemas/repository' - author: - $ref: '#/components/schemas/user' + repository: + $ref: "#/components/schemas/repository" + author: + $ref: "#/components/schemas/user" diff --git a/examples/v3.0/petstore-expanded.yaml b/examples/v3.0/petstore-expanded.yaml index 7e5bff0..fdeee95 100644 --- a/examples/v3.0/petstore-expanded.yaml +++ b/examples/v3.0/petstore-expanded.yaml @@ -40,20 +40,20 @@ paths: type: integer format: int32 responses: - '200': + "200": description: pet response content: application/json: schema: type: array items: - $ref: '#/components/schemas/Pet' + $ref: "#/components/schemas/Pet" default: description: unexpected error content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: "#/components/schemas/Error" post: description: Creates a new pet in the store. Duplicates are allowed operationId: addPet @@ -63,20 +63,20 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/NewPet' + $ref: "#/components/schemas/NewPet" responses: - '200': + "200": description: pet response content: application/json: schema: - $ref: '#/components/schemas/Pet' + $ref: "#/components/schemas/Pet" default: description: unexpected error content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: "#/components/schemas/Error" /pets/{id}: get: description: Returns a user based on a single ID, if the user does not have access to the pet @@ -90,18 +90,18 @@ paths: type: integer format: int64 responses: - '200': + "200": description: pet response content: application/json: schema: - $ref: '#/components/schemas/Pet' + $ref: "#/components/schemas/Pet" default: description: unexpected error content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: "#/components/schemas/Error" delete: description: deletes a single pet based on the ID supplied operationId: deletePet @@ -114,22 +114,22 @@ paths: type: integer format: int64 responses: - '204': + "204": description: pet deleted default: description: unexpected error content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: "#/components/schemas/Error" components: schemas: Pet: allOf: - - $ref: '#/components/schemas/NewPet' + - $ref: "#/components/schemas/NewPet" - type: object required: - - id + - id properties: id: type: integer @@ -138,12 +138,12 @@ components: NewPet: type: object required: - - name + - name properties: name: type: string tag: - type: string + type: string Error: type: object diff --git a/examples/v3.0/petstore.yaml b/examples/v3.0/petstore.yaml index 7ed987f..a956f24 100644 --- a/examples/v3.0/petstore.yaml +++ b/examples/v3.0/petstore.yaml @@ -23,7 +23,7 @@ paths: maximum: 100 format: int32 responses: - '200': + "200": description: A paged array of pets headers: x-next: @@ -31,7 +31,7 @@ paths: schema: type: string content: - application/json: + application/json: schema: $ref: "#/components/schemas/Pets" default: @@ -49,10 +49,10 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Pet' + $ref: "#/components/schemas/Pet" required: true responses: - '201': + "201": description: Null response default: description: unexpected error @@ -74,7 +74,7 @@ paths: schema: type: string responses: - '200': + "200": description: Expected response to a valid request content: application/json: diff --git a/examples/v3.0/uspto.yaml b/examples/v3.0/uspto.yaml index d301152..fb9d7e7 100644 --- a/examples/v3.0/uspto.yaml +++ b/examples/v3.0/uspto.yaml @@ -1,13 +1,13 @@ openapi: 3.0.1 servers: - - url: '{scheme}://developer.uspto.gov/ds-api' + - url: "{scheme}://developer.uspto.gov/ds-api" variables: scheme: - description: 'The Data Set API is accessible via https and http' + description: "The Data Set API is accessible via https and http" enum: - - 'https' - - 'http' - default: 'https' + - "https" + - "http" + default: "https" info: description: >- The Data Set API (DSAPI) allows the public users to discover and search @@ -23,7 +23,7 @@ info: title: USPTO Data Set API contact: name: Open Data Portal - url: 'https://developer.uspto.gov' + url: "https://developer.uspto.gov" email: developer@uspto.gov tags: - name: metadata @@ -38,29 +38,30 @@ paths: operationId: list-data-sets summary: List available data sets responses: - '200': + "200": description: Returns a list of data sets content: application/json: schema: - $ref: '#/components/schemas/dataSetList' + $ref: "#/components/schemas/dataSetList" example: { "total": 2, - "apis": [ - { - "apiKey": "oa_citations", - "apiVersionNumber": "v1", - "apiUrl": "https://developer.uspto.gov/ds-api/oa_citations/v1/fields", - "apiDocumentationUrl": "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/oa_citations.json" - }, - { - "apiKey": "cancer_moonshot", - "apiVersionNumber": "v1", - "apiUrl": "https://developer.uspto.gov/ds-api/cancer_moonshot/v1/fields", - "apiDocumentationUrl": "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/cancer_moonshot.json" - } - ] + "apis": + [ + { + "apiKey": "oa_citations", + "apiVersionNumber": "v1", + "apiUrl": "https://developer.uspto.gov/ds-api/oa_citations/v1/fields", + "apiDocumentationUrl": "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/oa_citations.json", + }, + { + "apiKey": "cancer_moonshot", + "apiVersionNumber": "v1", + "apiUrl": "https://developer.uspto.gov/ds-api/cancer_moonshot/v1/fields", + "apiDocumentationUrl": "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/cancer_moonshot.json", + }, + ], } /{dataset}/{version}/fields: get: @@ -78,7 +79,7 @@ paths: parameters: - name: dataset in: path - description: 'Name of the dataset.' + description: "Name of the dataset." required: true example: "oa_citations" schema: @@ -91,7 +92,7 @@ paths: schema: type: string responses: - '200': + "200": description: >- The dataset API for the given version is found and it is accessible to consume. @@ -99,7 +100,7 @@ paths: application/json: schema: type: string - '404': + "404": description: >- The combination of dataset name and version is not found in the system or it is not published yet to be consumed by public. @@ -134,13 +135,13 @@ paths: default: v1 - name: dataset in: path - description: 'Name of the dataset. In this case, the default value is oa_citations' + description: "Name of the dataset. In this case, the default value is oa_citations" required: true schema: type: string default: oa_citations responses: - '200': + "200": description: successful operation content: application/json: @@ -150,7 +151,7 @@ paths: type: object additionalProperties: type: object - '404': + "404": description: No matching record found for the given criteria. requestBody: content: @@ -167,7 +168,7 @@ paths: record objects. Each record structure would consist of all the fields and their corresponding values. type: string - default: '*:*' + default: "*:*" start: description: Starting record number. Default value is 0. type: integer diff --git a/examples/v3.1/non-oauth-scopes.yaml b/examples/v3.1/non-oauth-scopes.yaml index e757452..0a79135 100644 --- a/examples/v3.1/non-oauth-scopes.yaml +++ b/examples/v3.1/non-oauth-scopes.yaml @@ -7,13 +7,12 @@ paths: get: security: - bearerAuth: - - 'read:users' - - 'public' + - "read:users" + - "public" components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: jwt - description: 'note: non-oauth scopes are not defined at the securityScheme level' - + description: "note: non-oauth scopes are not defined at the securityScheme level" diff --git a/examples/v3.1/tictactoe.yaml b/examples/v3.1/tictactoe.yaml index 7f0e4fd..ddf3058 100644 --- a/examples/v3.1/tictactoe.yaml +++ b/examples/v3.1/tictactoe.yaml @@ -26,7 +26,7 @@ paths: security: - apiKey: [] - app2AppOauth: - - board:read + - board:read # Single square operations /board/{row}/{column}: @@ -56,7 +56,7 @@ paths: security: - bearerHttpAuthentication: [] - user2AppOauth: - - board:read + - board:read put: summary: Set a single board square description: Places a mark on the board and retrieves the whole board and the winner (if any). @@ -92,7 +92,7 @@ paths: security: - bearerHttpAuthentication: [] - user2AppOauth: - - board:write + - board:write components: parameters: @@ -179,4 +179,4 @@ components: scopes: # Reads and writes permitted via authorization code flow board:read: Read the board - board:write: Write to the board \ No newline at end of file + board:write: Write to the board diff --git a/examples/v3.1/webhook-example.yaml b/examples/v3.1/webhook-example.yaml index 2ac1cda..44fc73a 100644 --- a/examples/v3.1/webhook-example.yaml +++ b/examples/v3.1/webhook-example.yaml @@ -32,4 +32,3 @@ components: type: string tag: type: string -