From 3324562a4c1e75a1cc7da5d4f562dcb9f2f41d50 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 14 Aug 2024 16:42:30 +0200 Subject: [PATCH 01/15] Add pages for examples --- Gemfile.lock | 1 + _includes/example-api-description.md | 18 ++++++++++++++++++ examples/index.md | 9 +++++++++ examples/v3.0/api-with-examples.md | 13 +++++++++++++ examples/v3.0/callback-example.md | 13 +++++++++++++ examples/v3.0/link-example.md | 13 +++++++++++++ examples/v3.0/petstore-expanded.md | 13 +++++++++++++ examples/v3.0/petstore.md | 13 +++++++++++++ examples/v3.0/uspto.md | 13 +++++++++++++ examples/v3.1/non-oauth-scopes.md | 13 +++++++++++++ examples/v3.1/tictactoe.md | 13 +++++++++++++ examples/v3.1/webhook-example.md | 13 +++++++++++++ 12 files changed, 145 insertions(+) create mode 100644 _includes/example-api-description.md create mode 100644 examples/index.md create mode 100644 examples/v3.0/api-with-examples.md create mode 100644 examples/v3.0/callback-example.md create mode 100644 examples/v3.0/link-example.md create mode 100644 examples/v3.0/petstore-expanded.md create mode 100644 examples/v3.0/petstore.md create mode 100644 examples/v3.0/uspto.md create mode 100644 examples/v3.1/non-oauth-scopes.md create mode 100644 examples/v3.1/tictactoe.md create mode 100644 examples/v3.1/webhook-example.md diff --git a/Gemfile.lock b/Gemfile.lock index 3a00189..6148dc9 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -77,6 +77,7 @@ GEM PLATFORMS arm64-darwin-21 + arm64-darwin-23 x86_64-darwin-23 x86_64-linux diff --git a/_includes/example-api-description.md b/_includes/example-api-description.md new file mode 100644 index 0000000..127144e --- /dev/null +++ b/_includes/example-api-description.md @@ -0,0 +1,18 @@ +# {{ include.name }} + +{% assign json_file = include.name | append: ".json" %} +{% assign yaml_file = include.name | append: ".yaml" %} + +{{ include.description }} + +## JSON + +```json +{% include_relative {{ json_file }} %} +``` + +## YAML + +```yaml +{% include_relative {{ yaml_file }} %} +``` diff --git a/examples/index.md b/examples/index.md new file mode 100644 index 0000000..de34a50 --- /dev/null +++ b/examples/index.md @@ -0,0 +1,9 @@ +--- +layout: default +title: Example API Descriptions +nav_order: 6 +has_children: true +has_toc: true +--- + +# Example API Descriptions diff --git a/examples/v3.0/api-with-examples.md b/examples/v3.0/api-with-examples.md new file mode 100644 index 0000000..073e9a2 --- /dev/null +++ b/examples/v3.0/api-with-examples.md @@ -0,0 +1,13 @@ +--- +layout: default +title: api-with-examples +parent: Example API Descriptions +--- + +{% comment %} +{% capture description %} +Insert description here, then remove comment tag above and endcomment tag below +{% endcapture %} +{% endcomment %} + +{% include example-api-description.md name=page.title description=description %} diff --git a/examples/v3.0/callback-example.md b/examples/v3.0/callback-example.md new file mode 100644 index 0000000..70deefd --- /dev/null +++ b/examples/v3.0/callback-example.md @@ -0,0 +1,13 @@ +--- +layout: default +title: callback-example +parent: Example API Descriptions +--- + +{% comment %} +{% capture description %} +Insert description here, then remove comment tag above and endcomment tag below +{% endcapture %} +{% endcomment %} + +{% include example-api-description.md name=page.title description=description %} diff --git a/examples/v3.0/link-example.md b/examples/v3.0/link-example.md new file mode 100644 index 0000000..9881ccc --- /dev/null +++ b/examples/v3.0/link-example.md @@ -0,0 +1,13 @@ +--- +layout: default +title: link-example +parent: Example API Descriptions +--- + +{% comment %} +{% capture description %} +Insert description here, then remove comment tag above and endcomment tag below +{% endcapture %} +{% endcomment %} + +{% include example-api-description.md name=page.title description=description %} diff --git a/examples/v3.0/petstore-expanded.md b/examples/v3.0/petstore-expanded.md new file mode 100644 index 0000000..62ef8e9 --- /dev/null +++ b/examples/v3.0/petstore-expanded.md @@ -0,0 +1,13 @@ +--- +layout: default +title: petstore-expanded +parent: Example API Descriptions +--- + +{% comment %} +{% capture description %} +Insert description here, then remove comment tag above and endcomment tag below +{% endcapture %} +{% endcomment %} + +{% include example-api-description.md name=page.title description=description %} diff --git a/examples/v3.0/petstore.md b/examples/v3.0/petstore.md new file mode 100644 index 0000000..e385167 --- /dev/null +++ b/examples/v3.0/petstore.md @@ -0,0 +1,13 @@ +--- +layout: default +title: petstore +parent: Example API Descriptions +--- + +{% comment %} +{% capture description %} +Insert description here, then remove comment tag above and endcomment tag below +{% endcapture %} +{% endcomment %} + +{% include example-api-description.md name=page.title description=description %} diff --git a/examples/v3.0/uspto.md b/examples/v3.0/uspto.md new file mode 100644 index 0000000..f5a5f50 --- /dev/null +++ b/examples/v3.0/uspto.md @@ -0,0 +1,13 @@ +--- +layout: default +title: uspto +parent: Example API Descriptions +--- + +{% comment %} +{% capture description %} +Insert description here, then remove comment tag above and endcomment tag below +{% endcapture %} +{% endcomment %} + +{% include example-api-description.md name=page.title description=description %} diff --git a/examples/v3.1/non-oauth-scopes.md b/examples/v3.1/non-oauth-scopes.md new file mode 100644 index 0000000..7b1cd8c --- /dev/null +++ b/examples/v3.1/non-oauth-scopes.md @@ -0,0 +1,13 @@ +--- +layout: default +title: non-oauth-scopes +parent: Example API Descriptions +--- + +{% comment %} +{% capture description %} +Insert description here, then remove comment tag above and endcomment tag below +{% endcapture %} +{% endcomment %} + +{% include example-api-description.md name=page.title description=description %} diff --git a/examples/v3.1/tictactoe.md b/examples/v3.1/tictactoe.md new file mode 100644 index 0000000..9d98f07 --- /dev/null +++ b/examples/v3.1/tictactoe.md @@ -0,0 +1,13 @@ +--- +layout: default +title: tictactoe +parent: Example API Descriptions +--- + +{% comment %} +{% capture description %} +Insert description here, then remove comment tag above and endcomment tag below +{% endcapture %} +{% endcomment %} + +{% include example-api-description.md name=page.title description=description %} diff --git a/examples/v3.1/webhook-example.md b/examples/v3.1/webhook-example.md new file mode 100644 index 0000000..c3ce2ed --- /dev/null +++ b/examples/v3.1/webhook-example.md @@ -0,0 +1,13 @@ +--- +layout: default +title: webhook-example +parent: Example API Descriptions +--- + +{% comment %} +{% capture description %} +Insert description here, then remove comment tag above and endcomment tag below +{% endcapture %} +{% endcomment %} + +{% include example-api-description.md name=page.title description=description %} From a69874ba08535870c669c50619fb62fac416ed17 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 14 Aug 2024 16:46:41 +0200 Subject: [PATCH 02/15] 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 - From e3ffb8dc8d5be54b1464eb4fcee22b69a968bbb1 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 14 Aug 2024 17:02:37 +0200 Subject: [PATCH 03/15] Update examples-tests.yaml --- .github/workflows/examples-tests.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/examples-tests.yaml b/.github/workflows/examples-tests.yaml index 9e416b4..e112673 100644 --- a/.github/workflows/examples-tests.yaml +++ b/.github/workflows/examples-tests.yaml @@ -1,4 +1,4 @@ -name: schema-test +name: examples-test # Author: @MikeRalphson / runs @jdesrosiers tests # Issue: https://github.com/OAI/OpenAPI-Specification/pull/2489 From d22d202fbaefb9146609be0f1c2595987d30c019 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 14 Aug 2024 17:30:37 +0200 Subject: [PATCH 04/15] Suppress highlighting of errors because the highlighted ones false positives (bug in kramdown/rouge? don't want to invest time), and we test the YAML files against the JSON Schema for OpenAPI, so they are more than just syntactically correct --- _includes/example-api-description.md | 7 ++----- _sass/custom/custom.scss | 8 ++++++-- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/_includes/example-api-description.md b/_includes/example-api-description.md index 127144e..23bfb77 100644 --- a/_includes/example-api-description.md +++ b/_includes/example-api-description.md @@ -1,18 +1,15 @@ # {{ include.name }} -{% assign json_file = include.name | append: ".json" %} -{% assign yaml_file = include.name | append: ".yaml" %} - {{ include.description }} ## JSON ```json -{% include_relative {{ json_file }} %} +{% include_relative {{ include.name | append: ".json" }} %} ``` ## YAML ```yaml -{% include_relative {{ yaml_file }} %} +{% include_relative {{ include.name | append: ".yaml" }} %} ``` diff --git a/_sass/custom/custom.scss b/_sass/custom/custom.scss index eb8d500..82921f9 100644 --- a/_sass/custom/custom.scss +++ b/_sass/custom/custom.scss @@ -2,7 +2,11 @@ object { width: 100%; } - .nav-list .nav-list-item .nav-list-expander { color: #1d781d !important; -} \ No newline at end of file +} + +.highlight .err { + color: inherit; + background-color: inherit; +} From a6bd0df09a15a106953f55a13721449149255e94 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 15 Aug 2024 12:46:40 +0200 Subject: [PATCH 05/15] prettier --single-quote examples/*/*.yaml --- examples/v3.0/api-with-examples.yaml | 114 +++++++++++++-------------- examples/v3.0/callback-example.yaml | 8 +- examples/v3.0/link-example.yaml | 36 ++++----- examples/v3.0/petstore-expanded.yaml | 28 +++---- examples/v3.0/petstore.yaml | 22 +++--- examples/v3.0/uspto.yaml | 54 ++++++------- examples/v3.1/non-oauth-scopes.yaml | 6 +- examples/v3.1/tictactoe.yaml | 58 +++++++------- examples/v3.1/webhook-example.yaml | 4 +- 9 files changed, 165 insertions(+), 165 deletions(-) diff --git a/examples/v3.0/api-with-examples.yaml b/examples/v3.0/api-with-examples.yaml index 62733df..d541060 100644 --- a/examples/v3.0/api-with-examples.yaml +++ b/examples/v3.0/api-with-examples.yaml @@ -1,4 +1,4 @@ -openapi: "3.0.0" +openapi: '3.0.0' info: title: Simple API overview version: 2.0.0 @@ -8,7 +8,7 @@ paths: operationId: listVersionsv2 summary: List API versions responses: - "200": + '200': description: |- 200 response content: @@ -17,35 +17,35 @@ paths: foo: value: { - "versions": + 'versions': [ { - "status": "CURRENT", - "updated": "2011-01-21T11:33:21Z", - "id": "v2.0", - "links": + 'status': 'CURRENT', + 'updated': '2011-01-21T11:33:21Z', + 'id': 'v2.0', + '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": + 'status': 'EXPERIMENTAL', + 'updated': '2013-07-23T11:33:21Z', + 'id': 'v3.0', + '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: @@ -84,7 +84,7 @@ paths: operationId: getVersionDetailsv2 summary: Show API version details responses: - "200": + '200': description: |- 200 response content: @@ -93,47 +93,47 @@ paths: foo: value: { - "version": + 'version': { - "status": "CURRENT", - "updated": "2011-01-21T11:33:21Z", - "media-types": + 'status': 'CURRENT', + 'updated': '2011-01-21T11:33:21Z', + 'media-types': [ { - "base": "application/xml", - "type": "application/vnd.openstack.compute+xml;version=2", + 'base': 'application/xml', + 'type': 'application/vnd.openstack.compute+xml;version=2', }, { - "base": "application/json", - "type": "application/vnd.openstack.compute+json;version=2", + 'base': 'application/json', + 'type': 'application/vnd.openstack.compute+json;version=2', }, ], - "id": "v2.0", - "links": + 'id': 'v2.0', + 'links': [ { - "href": "http://127.0.0.1:8774/v2/", - "rel": "self", + '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/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', }, { - "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: @@ -142,37 +142,37 @@ paths: foo: value: { - "version": + 'version': { - "status": "CURRENT", - "updated": "2011-01-21T11:33:21Z", - "media-types": + 'status': 'CURRENT', + 'updated': '2011-01-21T11:33:21Z', + 'media-types': [ { - "base": "application/xml", - "type": "application/vnd.openstack.compute+xml;version=2", + 'base': 'application/xml', + 'type': 'application/vnd.openstack.compute+xml;version=2', }, { - "base": "application/json", - "type": "application/vnd.openstack.compute+json;version=2", + 'base': 'application/json', + 'type': 'application/vnd.openstack.compute+json;version=2', }, ], - "id": "v2.0", - "links": + 'id': 'v2.0', + 'links': [ { - "href": "http://23.253.228.211:8774/v2/", - "rel": "self", + '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/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', }, ], }, diff --git a/examples/v3.0/callback-example.yaml b/examples/v3.0/callback-example.yaml index 0bd0f93..262b8df 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 8616f32..ea90bdc 100644 --- a/examples/v3.0/link-example.yaml +++ b/examples/v3.0/link-example.yaml @@ -13,15 +13,15 @@ paths: schema: type: string responses: - "200": + '200': description: The User content: application/json: schema: - $ref: "#/components/schemas/user" + $ref: '#/components/schemas/user' links: userRepositories: - $ref: "#/components/links/UserRepositories" + $ref: '#/components/links/UserRepositories' /2.0/repositories/{username}: get: operationId: getRepositoriesByOwner @@ -32,17 +32,17 @@ paths: schema: type: string responses: - "200": + '200': description: repositories owned by the supplied user content: application/json: schema: type: array items: - $ref: "#/components/schemas/repository" + $ref: '#/components/schemas/repository' links: userRepository: - $ref: "#/components/links/UserRepository" + $ref: '#/components/links/UserRepository' /2.0/repositories/{username}/{slug}: get: operationId: getRepository @@ -58,15 +58,15 @@ paths: schema: type: string responses: - "200": + '200': description: The repository content: application/json: schema: - $ref: "#/components/schemas/repository" + $ref: '#/components/schemas/repository' links: repositoryPullRequests: - $ref: "#/components/links/RepositoryPullRequests" + $ref: '#/components/links/RepositoryPullRequests' /2.0/repositories/{username}/{slug}/pullrequests: get: operationId: getPullRequestsByRepository @@ -90,14 +90,14 @@ paths: - merged - declined responses: - "200": + '200': description: an array of pull request objects content: application/json: schema: type: array items: - $ref: "#/components/schemas/pullrequest" + $ref: '#/components/schemas/pullrequest' /2.0/repositories/{username}/{slug}/pullrequests/{pid}: get: operationId: getPullRequestsById @@ -118,15 +118,15 @@ paths: schema: type: string responses: - "200": + '200': description: a pull request object content: application/json: schema: - $ref: "#/components/schemas/pullrequest" + $ref: '#/components/schemas/pullrequest' links: pullRequestMerge: - $ref: "#/components/links/PullRequestMerge" + $ref: '#/components/links/PullRequestMerge' /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge: post: operationId: mergePullRequest @@ -147,7 +147,7 @@ paths: schema: type: string responses: - "204": + '204': description: the PR was successfully merged components: links: @@ -189,7 +189,7 @@ components: slug: type: string owner: - $ref: "#/components/schemas/user" + $ref: '#/components/schemas/user' pullrequest: type: object properties: @@ -198,6 +198,6 @@ components: title: type: string repository: - $ref: "#/components/schemas/repository" + $ref: '#/components/schemas/repository' author: - $ref: "#/components/schemas/user" + $ref: '#/components/schemas/user' diff --git a/examples/v3.0/petstore-expanded.yaml b/examples/v3.0/petstore-expanded.yaml index fdeee95..c4d59a6 100644 --- a/examples/v3.0/petstore-expanded.yaml +++ b/examples/v3.0/petstore-expanded.yaml @@ -1,4 +1,4 @@ -openapi: "3.0.0" +openapi: '3.0.0' info: version: 1.0.0 title: Swagger Petstore @@ -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,19 +114,19 @@ 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 diff --git a/examples/v3.0/petstore.yaml b/examples/v3.0/petstore.yaml index a956f24..b01683d 100644 --- a/examples/v3.0/petstore.yaml +++ b/examples/v3.0/petstore.yaml @@ -1,4 +1,4 @@ -openapi: "3.0.0" +openapi: '3.0.0' info: version: 1.0.0 title: Swagger Petstore @@ -23,7 +23,7 @@ paths: maximum: 100 format: int32 responses: - "200": + '200': description: A paged array of pets headers: x-next: @@ -33,13 +33,13 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/Pets" + $ref: '#/components/schemas/Pets' default: description: unexpected error content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: '#/components/schemas/Error' post: summary: Create a pet operationId: createPets @@ -49,17 +49,17 @@ 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 content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: '#/components/schemas/Error' /pets/{petId}: get: summary: Info for a specific pet @@ -74,18 +74,18 @@ paths: schema: type: string responses: - "200": + '200': description: Expected response to a valid request 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' components: schemas: Pet: @@ -105,7 +105,7 @@ components: type: array maxItems: 100 items: - $ref: "#/components/schemas/Pet" + $ref: '#/components/schemas/Pet' Error: type: object required: diff --git a/examples/v3.0/uspto.yaml b/examples/v3.0/uspto.yaml index fb9d7e7..2186e50 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,28 +38,28 @@ 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": + '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': '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", + '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', }, ], } @@ -79,20 +79,20 @@ paths: parameters: - name: dataset in: path - description: "Name of the dataset." + description: 'Name of the dataset.' required: true - example: "oa_citations" + example: 'oa_citations' schema: type: string - name: version in: path description: Version of the dataset. required: true - example: "v1" + example: 'v1' schema: type: string responses: - "200": + '200': description: >- The dataset API for the given version is found and it is accessible to consume. @@ -100,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. @@ -135,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: @@ -151,7 +151,7 @@ paths: type: object additionalProperties: type: object - "404": + '404': description: No matching record found for the given criteria. requestBody: content: @@ -168,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 0a79135..2e20847 100644 --- a/examples/v3.1/non-oauth-scopes.yaml +++ b/examples/v3.1/non-oauth-scopes.yaml @@ -7,12 +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 ddf3058..3541543 100644 --- a/examples/v3.1/tictactoe.yaml +++ b/examples/v3.1/tictactoe.yaml @@ -17,12 +17,12 @@ paths: - Gameplay operationId: get-board responses: - "200": - description: "OK" + '200': + description: 'OK' content: application/json: schema: - $ref: "#/components/schemas/status" + $ref: '#/components/schemas/status' security: - apiKey: [] - app2AppOauth: @@ -31,8 +31,8 @@ paths: # Single square operations /board/{row}/{column}: parameters: - - $ref: "#/components/parameters/rowParam" - - $ref: "#/components/parameters/columnParam" + - $ref: '#/components/parameters/rowParam' + - $ref: '#/components/parameters/columnParam' get: summary: Get a single board square description: Retrieves the requested square. @@ -40,19 +40,19 @@ paths: - Gameplay operationId: get-square responses: - "200": - description: "OK" + '200': + description: 'OK' content: application/json: schema: - $ref: "#/components/schemas/mark" - "400": + $ref: '#/components/schemas/mark' + '400': description: The provided parameters are incorrect content: text/html: schema: - $ref: "#/components/schemas/errorMessage" - example: "Illegal coordinates" + $ref: '#/components/schemas/errorMessage' + example: 'Illegal coordinates' security: - bearerHttpAuthentication: [] - user2AppOauth: @@ -68,27 +68,27 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/mark" + $ref: '#/components/schemas/mark' responses: - "200": - description: "OK" + '200': + description: 'OK' content: application/json: schema: - $ref: "#/components/schemas/status" - "400": + $ref: '#/components/schemas/status' + '400': description: The provided parameters are incorrect content: text/html: schema: - $ref: "#/components/schemas/errorMessage" + $ref: '#/components/schemas/errorMessage' examples: illegalCoordinates: - value: "Illegal coordinates." + value: 'Illegal coordinates.' notEmpty: - value: "Square is not empty." + value: 'Square is not empty.' invalidMark: - value: "Invalid Mark (X or O)." + value: 'Invalid Mark (X or O).' security: - bearerHttpAuthentication: [] - user2AppOauth: @@ -102,14 +102,14 @@ components: in: path required: true schema: - $ref: "#/components/schemas/coordinate" + $ref: '#/components/schemas/coordinate' columnParam: description: Board column (horizontal coordinate) name: column in: path required: true schema: - $ref: "#/components/schemas/coordinate" + $ref: '#/components/schemas/coordinate' schemas: errorMessage: type: string @@ -122,9 +122,9 @@ components: example: 1 mark: type: string - enum: [".", "X", "O"] + enum: ['.', 'X', 'O'] description: Possible values for a board square. `.` means empty square. - example: "." + example: '.' board: type: array maxItems: 3 @@ -134,19 +134,19 @@ components: maxItems: 3 minItems: 3 items: - $ref: "#/components/schemas/mark" + $ref: '#/components/schemas/mark' winner: type: string - enum: [".", "X", "O"] + enum: ['.', 'X', 'O'] description: Winner of the game. `.` means nobody has won yet. - example: "." + example: '.' status: type: object properties: winner: - $ref: "#/components/schemas/winner" + $ref: '#/components/schemas/winner' board: - $ref: "#/components/schemas/board" + $ref: '#/components/schemas/board' securitySchemes: defaultApiKey: description: API key provided in console diff --git a/examples/v3.1/webhook-example.yaml b/examples/v3.1/webhook-example.yaml index 44fc73a..7aa10cf 100644 --- a/examples/v3.1/webhook-example.yaml +++ b/examples/v3.1/webhook-example.yaml @@ -13,9 +13,9 @@ webhooks: content: application/json: schema: - $ref: "#/components/schemas/Pet" + $ref: '#/components/schemas/Pet' responses: - "200": + '200': description: Return a 200 status to indicate that the data was received successfully components: From 81590a14a44be0aebb8ad460826a61298010b549 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 15 Aug 2024 12:58:10 +0200 Subject: [PATCH 06/15] Update api-with-examples.yaml --- examples/v3.0/api-with-examples.yaml | 172 +++++++++------------------ 1 file changed, 57 insertions(+), 115 deletions(-) diff --git a/examples/v3.0/api-with-examples.yaml b/examples/v3.0/api-with-examples.yaml index d541060..59fec58 100644 --- a/examples/v3.0/api-with-examples.yaml +++ b/examples/v3.0/api-with-examples.yaml @@ -1,4 +1,4 @@ -openapi: '3.0.0' +openapi: 3.0.0 info: title: Simple API overview version: 2.0.0 @@ -9,45 +9,27 @@ paths: summary: List API versions responses: '200': - description: |- - 200 response + description: 200 response content: 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 '300': - description: |- - 300 response + description: 300 response content: application/json: examples: @@ -85,95 +67,55 @@ paths: summary: Show API version details responses: '200': - description: |- - 200 response + description: 200 response content: 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': - description: |- - 203 response + description: 203 response content: 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 From be248e49bd098dfe8413acf4a38ba23218d812be Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 15 Aug 2024 13:03:07 +0200 Subject: [PATCH 07/15] Reformatted with yq --- examples/v3.0/petstore-expanded.yaml | 4 +- examples/v3.0/petstore.yaml | 2 +- examples/v3.0/uspto.yaml | 105 ++++++++------------------- examples/v3.1/non-oauth-scopes.yaml | 4 +- examples/v3.1/tictactoe.yaml | 30 ++++---- examples/v3.1/webhook-example.yaml | 1 - 6 files changed, 50 insertions(+), 96 deletions(-) diff --git a/examples/v3.0/petstore-expanded.yaml b/examples/v3.0/petstore-expanded.yaml index c4d59a6..1b5a6ce 100644 --- a/examples/v3.0/petstore-expanded.yaml +++ b/examples/v3.0/petstore-expanded.yaml @@ -1,4 +1,4 @@ -openapi: '3.0.0' +openapi: 3.0.0 info: version: 1.0.0 title: Swagger Petstore @@ -134,7 +134,6 @@ components: id: type: integer format: int64 - NewPet: type: object required: @@ -144,7 +143,6 @@ components: type: string tag: type: string - Error: type: object required: diff --git a/examples/v3.0/petstore.yaml b/examples/v3.0/petstore.yaml index b01683d..98f62c1 100644 --- a/examples/v3.0/petstore.yaml +++ b/examples/v3.0/petstore.yaml @@ -1,4 +1,4 @@ -openapi: '3.0.0' +openapi: 3.0.0 info: version: 1.0.0 title: Swagger Petstore diff --git a/examples/v3.0/uspto.yaml b/examples/v3.0/uspto.yaml index 2186e50..ce9c124 100644 --- a/examples/v3.0/uspto.yaml +++ b/examples/v3.0/uspto.yaml @@ -3,27 +3,18 @@ servers: - 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 - USPTO exported data sets. This is a generic API that allows USPTO users to - make any CSV based data files searchable through API. With the help of GET - call, it returns the list of data fields that are searchable. With the help - of POST call, data can be fetched based on the filters on the field names. - Please note that POST call is used to search the actual data. The reason for - the POST call is that it allows users to specify any complex search criteria - without worry about the GET size limitations as well as encoding of the - input parameters. + description: The Data Set API (DSAPI) allows the public users to discover and search USPTO exported data sets. This is a generic API that allows USPTO users to make any CSV based data files searchable through API. With the help of GET call, it returns the list of data fields that are searchable. With the help of POST call, data can be fetched based on the filters on the field names. Please note that POST call is used to search the actual data. The reason for the POST call is that it allows users to specify any complex search criteria without worry about the GET size limitations as well as encoding of the input parameters. version: 1.0.0 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 @@ -45,65 +36,47 @@ paths: schema: $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', - }, - ], - } + 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 /{dataset}/{version}/fields: get: tags: - metadata - summary: >- - Provides the general information about the API and the list of fields - that can be used to query the dataset. - description: >- - This GET API returns the list of all the searchable field names that are - in the oa_citations. Please see the 'fields' attribute which returns an - array of field names. Each field or a combination of fields can be - searched using the syntax options shown below. + summary: Provides the general information about the API and the list of fields that can be used to query the dataset. + description: This GET API returns the list of all the searchable field names that are in the oa_citations. Please see the 'fields' attribute which returns an array of field names. Each field or a combination of fields can be searched using the syntax options shown below. operationId: list-searchable-fields parameters: - name: dataset in: path - description: 'Name of the dataset.' + description: Name of the dataset. required: true - example: 'oa_citations' + example: oa_citations schema: type: string - name: version in: path description: Version of the dataset. required: true - example: 'v1' + example: v1 schema: type: string responses: '200': - description: >- - The dataset API for the given version is found and it is accessible - to consume. + description: The dataset API for the given version is found and it is accessible to consume. content: application/json: schema: type: string '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. + 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. content: application/json: schema: @@ -112,18 +85,8 @@ paths: post: tags: - search - summary: >- - Provides search capability for the data set with the given search - criteria. - description: >- - This API is based on Solr/Lucene Search. The data is indexed using - SOLR. This GET API returns the list of all the searchable field names - that are in the Solr Index. Please see the 'fields' attribute which - returns an array of field names. Each field or a combination of fields - can be searched using the Solr/Lucene Syntax. Please refer - https://lucene.apache.org/core/3_6_2/queryparsersyntax.html#Overview for - the query syntax. List of field names that are searchable can be - determined using above GET api. + summary: Provides search capability for the data set with the given search criteria. + description: This API is based on Solr/Lucene Search. The data is indexed using SOLR. This GET API returns the list of all the searchable field names that are in the Solr Index. Please see the 'fields' attribute which returns an array of field names. Each field or a combination of fields can be searched using the Solr/Lucene Syntax. Please refer https://lucene.apache.org/core/3_6_2/queryparsersyntax.html#Overview for the query syntax. List of field names that are searchable can be determined using above GET api. operationId: perform-search parameters: - name: version @@ -135,7 +98,7 @@ 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 @@ -160,13 +123,7 @@ paths: type: object properties: criteria: - description: >- - Uses Lucene Query Syntax in the format of - propertyName:value, propertyName:[num1 TO num2] and date - range format: propertyName:[yyyyMMdd TO yyyyMMdd]. In the - response please see the 'docs' element which has the list of - record objects. Each record structure would consist of all - the fields and their corresponding values. + description: "Uses Lucene Query Syntax in the format of propertyName:value, propertyName:[num1 TO num2] and date range format: propertyName:[yyyyMMdd TO yyyyMMdd]. In the response please see the 'docs' element which has the list of record objects. Each record structure would consist of all the fields and their corresponding values." type: string default: '*:*' start: @@ -174,11 +131,7 @@ paths: type: integer default: 0 rows: - description: >- - Specify number of rows to be returned. If you run the search - with default values, in the response you will see 'numFound' - attribute which will tell the number of records available in - the dataset. + description: Specify number of rows to be returned. If you run the search with default values, in the response you will see 'numFound' attribute which will tell the number of records available in the dataset. type: integer default: 100 required: @@ -204,7 +157,7 @@ components: apiUrl: type: string format: uriref - description: "The URL describing the dataset's fields" + description: The URL describing the dataset's fields apiDocumentationUrl: type: string format: uriref diff --git a/examples/v3.1/non-oauth-scopes.yaml b/examples/v3.1/non-oauth-scopes.yaml index 2e20847..ac9fc8d 100644 --- a/examples/v3.1/non-oauth-scopes.yaml +++ b/examples/v3.1/non-oauth-scopes.yaml @@ -7,8 +7,8 @@ paths: get: security: - bearerAuth: - - 'read:users' - - 'public' + - read:users + - public components: securitySchemes: bearerAuth: diff --git a/examples/v3.1/tictactoe.yaml b/examples/v3.1/tictactoe.yaml index 3541543..84047bd 100644 --- a/examples/v3.1/tictactoe.yaml +++ b/examples/v3.1/tictactoe.yaml @@ -18,7 +18,7 @@ paths: operationId: get-board responses: '200': - description: 'OK' + description: OK content: application/json: schema: @@ -27,7 +27,6 @@ paths: - apiKey: [] - app2AppOauth: - board:read - # Single square operations /board/{row}/{column}: parameters: @@ -41,7 +40,7 @@ paths: operationId: get-square responses: '200': - description: 'OK' + description: OK content: application/json: schema: @@ -52,7 +51,7 @@ paths: text/html: schema: $ref: '#/components/schemas/errorMessage' - example: 'Illegal coordinates' + example: Illegal coordinates security: - bearerHttpAuthentication: [] - user2AppOauth: @@ -71,7 +70,7 @@ paths: $ref: '#/components/schemas/mark' responses: '200': - description: 'OK' + description: OK content: application/json: schema: @@ -84,16 +83,15 @@ paths: $ref: '#/components/schemas/errorMessage' examples: illegalCoordinates: - value: 'Illegal coordinates.' + value: Illegal coordinates. notEmpty: - value: 'Square is not empty.' + value: Square is not empty. invalidMark: - value: 'Invalid Mark (X or O).' + value: Invalid Mark (X or O). security: - bearerHttpAuthentication: [] - user2AppOauth: - board:write - components: parameters: rowParam: @@ -122,9 +120,12 @@ components: example: 1 mark: type: string - enum: ['.', 'X', 'O'] + enum: + - . + - X + - O description: Possible values for a board square. `.` means empty square. - example: '.' + example: . board: type: array maxItems: 3 @@ -137,9 +138,12 @@ components: $ref: '#/components/schemas/mark' winner: type: string - enum: ['.', 'X', 'O'] + enum: + - . + - X + - O description: Winner of the game. `.` means nobody has won yet. - example: '.' + example: . status: type: object properties: diff --git a/examples/v3.1/webhook-example.yaml b/examples/v3.1/webhook-example.yaml index 7aa10cf..9d69684 100644 --- a/examples/v3.1/webhook-example.yaml +++ b/examples/v3.1/webhook-example.yaml @@ -17,7 +17,6 @@ webhooks: responses: '200': description: Return a 200 status to indicate that the data was received successfully - components: schemas: Pet: From 699e846fafc19ac81c92085be4cd458a99665fc6 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 15 Aug 2024 13:04:25 +0200 Subject: [PATCH 08/15] prettier on json --- examples/v3.0/api-with-examples.json | 2 +- examples/v3.0/callback-example.json | 6 ++--- examples/v3.0/link-example.json | 8 ++---- examples/v3.0/petstore-expanded.json | 15 +++-------- examples/v3.0/petstore.json | 24 +++++------------- examples/v3.0/uspto.json | 23 +++++------------ examples/v3.1/non-oauth-scopes.json | 7 ++--- examples/v3.1/tictactoe.json | 38 +++++++--------------------- examples/v3.1/webhook-example.json | 7 ++--- 9 files changed, 34 insertions(+), 96 deletions(-) diff --git a/examples/v3.0/api-with-examples.json b/examples/v3.0/api-with-examples.json index 0fd2077..ecc992c 100644 --- a/examples/v3.0/api-with-examples.json +++ b/examples/v3.0/api-with-examples.json @@ -164,4 +164,4 @@ } } } -} \ No newline at end of file +} diff --git a/examples/v3.0/callback-example.json b/examples/v3.0/callback-example.json index 9a4df39..edae06a 100644 --- a/examples/v3.0/callback-example.json +++ b/examples/v3.0/callback-example.json @@ -28,9 +28,7 @@ "application/json": { "schema": { "description": "subscription information", - "required": [ - "subscriptionId" - ], + "required": ["subscriptionId"], "properties": { "subscriptionId": { "description": "this unique identifier allows management of the subscription", @@ -81,4 +79,4 @@ } } } -} \ No newline at end of file +} diff --git a/examples/v3.0/link-example.json b/examples/v3.0/link-example.json index bc98e63..e230387 100644 --- a/examples/v3.0/link-example.json +++ b/examples/v3.0/link-example.json @@ -137,11 +137,7 @@ "in": "query", "schema": { "type": "string", - "enum": [ - "open", - "merged", - "declined" - ] + "enum": ["open", "merged", "declined"] } } ], @@ -320,4 +316,4 @@ } } } -} \ No newline at end of file +} diff --git a/examples/v3.0/petstore-expanded.json b/examples/v3.0/petstore-expanded.json index 420eede..7315872 100644 --- a/examples/v3.0/petstore-expanded.json +++ b/examples/v3.0/petstore-expanded.json @@ -195,9 +195,7 @@ }, { "type": "object", - "required": [ - "id" - ], + "required": ["id"], "properties": { "id": { "type": "integer", @@ -209,9 +207,7 @@ }, "NewPet": { "type": "object", - "required": [ - "name" - ], + "required": ["name"], "properties": { "name": { "type": "string" @@ -223,10 +219,7 @@ }, "Error": { "type": "object", - "required": [ - "code", - "message" - ], + "required": ["code", "message"], "properties": { "code": { "type": "integer", @@ -239,4 +232,4 @@ } } } -} \ No newline at end of file +} diff --git a/examples/v3.0/petstore.json b/examples/v3.0/petstore.json index d14eb5e..9d717b6 100644 --- a/examples/v3.0/petstore.json +++ b/examples/v3.0/petstore.json @@ -17,9 +17,7 @@ "get": { "summary": "List all pets", "operationId": "listPets", - "tags": [ - "pets" - ], + "tags": ["pets"], "parameters": [ { "name": "limit", @@ -67,9 +65,7 @@ "post": { "summary": "Create a pet", "operationId": "createPets", - "tags": [ - "pets" - ], + "tags": ["pets"], "requestBody": { "content": { "application/json": { @@ -101,9 +97,7 @@ "get": { "summary": "Info for a specific pet", "operationId": "showPetById", - "tags": [ - "pets" - ], + "tags": ["pets"], "parameters": [ { "name": "petId", @@ -144,10 +138,7 @@ "schemas": { "Pet": { "type": "object", - "required": [ - "id", - "name" - ], + "required": ["id", "name"], "properties": { "id": { "type": "integer", @@ -170,10 +161,7 @@ }, "Error": { "type": "object", - "required": [ - "code", - "message" - ], + "required": ["code", "message"], "properties": { "code": { "type": "integer", @@ -186,4 +174,4 @@ } } } -} \ No newline at end of file +} diff --git a/examples/v3.0/uspto.json b/examples/v3.0/uspto.json index cd32f64..5c687e2 100644 --- a/examples/v3.0/uspto.json +++ b/examples/v3.0/uspto.json @@ -6,10 +6,7 @@ "variables": { "scheme": { "description": "The Data Set API is accessible via https and http", - "enum": [ - "https", - "http" - ], + "enum": ["https", "http"], "default": "https" } } @@ -38,9 +35,7 @@ "paths": { "/": { "get": { - "tags": [ - "metadata" - ], + "tags": ["metadata"], "operationId": "list-data-sets", "summary": "List available data sets", "responses": { @@ -76,9 +71,7 @@ }, "/{dataset}/{version}/fields": { "get": { - "tags": [ - "metadata" - ], + "tags": ["metadata"], "summary": "Provides the general information about the API and the list of fields that can be used to query the dataset.", "description": "This GET API returns the list of all the searchable field names that are in the oa_citations. Please see the 'fields' attribute which returns an array of field names. Each field or a combination of fields can be searched using the syntax options shown below.", "operationId": "list-searchable-fields", @@ -130,9 +123,7 @@ }, "/{dataset}/{version}/records": { "post": { - "tags": [ - "search" - ], + "tags": ["search"], "summary": "Provides search capability for the data set with the given search criteria.", "description": "This API is based on Solr/Lucene Search. The data is indexed using SOLR. This GET API returns the list of all the searchable field names that are in the Solr Index. Please see the 'fields' attribute which returns an array of field names. Each field or a combination of fields can be searched using the Solr/Lucene Syntax. Please refer https://lucene.apache.org/core/3_6_2/queryparsersyntax.html#Overview for the query syntax. List of field names that are searchable can be determined using above GET api.", "operationId": "perform-search", @@ -201,9 +192,7 @@ "default": 100 } }, - "required": [ - "criteria" - ] + "required": ["criteria"] } } } @@ -249,4 +238,4 @@ } } } -} \ No newline at end of file +} diff --git a/examples/v3.1/non-oauth-scopes.json b/examples/v3.1/non-oauth-scopes.json index b3e5990..6a39a72 100644 --- a/examples/v3.1/non-oauth-scopes.json +++ b/examples/v3.1/non-oauth-scopes.json @@ -9,10 +9,7 @@ "get": { "security": [ { - "bearerAuth": [ - "read:users", - "public" - ] + "bearerAuth": ["read:users", "public"] } ] } @@ -28,4 +25,4 @@ } } } -} \ No newline at end of file +} diff --git a/examples/v3.1/tictactoe.json b/examples/v3.1/tictactoe.json index 9ec11f7..901b5ae 100644 --- a/examples/v3.1/tictactoe.json +++ b/examples/v3.1/tictactoe.json @@ -15,9 +15,7 @@ "get": { "summary": "Get the whole board", "description": "Retrieves the current state of the board and the winner.", - "tags": [ - "Gameplay" - ], + "tags": ["Gameplay"], "operationId": "get-board", "responses": { "200": { @@ -36,9 +34,7 @@ "apiKey": [] }, { - "app2AppOauth": [ - "board:read" - ] + "app2AppOauth": ["board:read"] } ] } @@ -55,9 +51,7 @@ "get": { "summary": "Get a single board square", "description": "Retrieves the requested square.", - "tags": [ - "Gameplay" - ], + "tags": ["Gameplay"], "operationId": "get-square", "responses": { "200": { @@ -87,18 +81,14 @@ "bearerHttpAuthentication": [] }, { - "user2AppOauth": [ - "board:read" - ] + "user2AppOauth": ["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).", - "tags": [ - "Gameplay" - ], + "tags": ["Gameplay"], "operationId": "put-square", "requestBody": { "required": true, @@ -148,9 +138,7 @@ "bearerHttpAuthentication": [] }, { - "user2AppOauth": [ - "board:write" - ] + "user2AppOauth": ["board:write"] } ] } @@ -191,11 +179,7 @@ }, "mark": { "type": "string", - "enum": [ - ".", - "X", - "O" - ], + "enum": [".", "X", "O"], "description": "Possible values for a board square. `.` means empty square.", "example": "." }, @@ -214,11 +198,7 @@ }, "winner": { "type": "string", - "enum": [ - ".", - "X", - "O" - ], + "enum": [".", "X", "O"], "description": "Winner of the game. `.` means nobody has won yet.", "example": "." }, @@ -278,4 +258,4 @@ } } } -} \ No newline at end of file +} diff --git a/examples/v3.1/webhook-example.json b/examples/v3.1/webhook-example.json index 712a42f..d39d129 100644 --- a/examples/v3.1/webhook-example.json +++ b/examples/v3.1/webhook-example.json @@ -28,10 +28,7 @@ "components": { "schemas": { "Pet": { - "required": [ - "id", - "name" - ], + "required": ["id", "name"], "properties": { "id": { "type": "integer", @@ -47,4 +44,4 @@ } } } -} \ No newline at end of file +} From ca4a587ef2f078ca750009f982efd7a25ee5cbb4 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 16 Aug 2024 10:36:05 +0200 Subject: [PATCH 09/15] Don't yamlize examples --- examples/v3.0/api-with-examples.yaml | 158 ++++++++++++++++++--------- examples/v3.0/uspto.yaml | 27 +++-- 2 files changed, 123 insertions(+), 62 deletions(-) diff --git a/examples/v3.0/api-with-examples.yaml b/examples/v3.0/api-with-examples.yaml index 59fec58..08bfa42 100644 --- a/examples/v3.0/api-with-examples.yaml +++ b/examples/v3.0/api-with-examples.yaml @@ -15,19 +15,35 @@ paths: 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", + }, + ], + }, + ], + } '300': description: 300 response content: @@ -73,27 +89,47 @@ paths: 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': description: 203 response content: @@ -101,21 +137,39 @@ paths: 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/uspto.yaml b/examples/v3.0/uspto.yaml index ce9c124..b57439e 100644 --- a/examples/v3.0/uspto.yaml +++ b/examples/v3.0/uspto.yaml @@ -36,16 +36,23 @@ paths: schema: $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 + { + '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', + }, + ], + } /{dataset}/{version}/fields: get: tags: From 1053c15f2eb2393d07bbc5f05c527ea8bcd1a256 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 16 Aug 2024 10:40:39 +0200 Subject: [PATCH 10/15] No superfluous trailing commas --- examples/v3.0/api-with-examples.yaml | 115 ++++++++++++++------------- 1 file changed, 59 insertions(+), 56 deletions(-) diff --git a/examples/v3.0/api-with-examples.yaml b/examples/v3.0/api-with-examples.yaml index 08bfa42..5229bd8 100644 --- a/examples/v3.0/api-with-examples.yaml +++ b/examples/v3.0/api-with-examples.yaml @@ -8,7 +8,7 @@ paths: operationId: listVersionsv2 summary: List API versions responses: - '200': + "200": description: 200 response content: application/json: @@ -26,9 +26,9 @@ paths: [ { "href": "http://127.0.0.1:8774/v2/", - "rel": "self", - }, - ], + "rel": "self" + } + ] }, { "status": "EXPERIMENTAL", @@ -38,51 +38,54 @@ paths: [ { "href": "http://127.0.0.1:8774/v3/", - "rel": "self", - }, - ], - }, - ], + "rel": "self" + } + ] + } + ] } - '300': + "300": description: 300 response content: application/json: examples: foo: - value: | + 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: @@ -98,39 +101,39 @@ paths: [ { "base": "application/xml", - "type": "application/vnd.openstack.compute+xml;version=2", + "type": "application/vnd.openstack.compute+xml;version=2" }, { "base": "application/json", - "type": "application/vnd.openstack.compute+json;version=2", - }, + "type": "application/vnd.openstack.compute+json;version=2" + } ], "id": "v2.0", "links": [ { "href": "http://127.0.0.1:8774/v2/", - "rel": "self", + "rel": "self" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", "type": "application/pdf", - "rel": "describedby", + "rel": "describedby" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", "type": "application/vnd.sun.wadl+xml", - "rel": "describedby", + "rel": "describedby" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", "type": "application/vnd.sun.wadl+xml", - "rel": "describedby", - }, - ], - }, + "rel": "describedby" + } + ] + } } - '203': + "203": description: 203 response content: application/json: @@ -146,30 +149,30 @@ paths: [ { "base": "application/xml", - "type": "application/vnd.openstack.compute+xml;version=2", + "type": "application/vnd.openstack.compute+xml;version=2" }, { "base": "application/json", - "type": "application/vnd.openstack.compute+json;version=2", - }, + "type": "application/vnd.openstack.compute+json;version=2" + } ], "id": "v2.0", "links": [ { "href": "http://23.253.228.211:8774/v2/", - "rel": "self", + "rel": "self" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", "type": "application/pdf", - "rel": "describedby", + "rel": "describedby" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", "type": "application/vnd.sun.wadl+xml", - "rel": "describedby", - }, - ], - }, + "rel": "describedby" + } + ] + } } From 3a735bbc1ef33117ebe2a1d29db7c0f2f4e5db7d Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 16 Aug 2024 10:44:50 +0200 Subject: [PATCH 11/15] Update api-with-examples.yaml --- examples/v3.0/api-with-examples.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/examples/v3.0/api-with-examples.yaml b/examples/v3.0/api-with-examples.yaml index 5229bd8..a94b294 100644 --- a/examples/v3.0/api-with-examples.yaml +++ b/examples/v3.0/api-with-examples.yaml @@ -8,7 +8,7 @@ paths: operationId: listVersionsv2 summary: List API versions responses: - "200": + '200': description: 200 response content: application/json: @@ -44,7 +44,7 @@ paths: } ] } - "300": + '300': description: 300 response content: application/json: @@ -133,7 +133,7 @@ paths: ] } } - "203": + '203': description: 203 response content: application/json: From 71e4bc1e6634d0f4761c143f264a350f6a8e7c1f Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 16 Aug 2024 10:51:27 +0200 Subject: [PATCH 12/15] Preserve text blocks --- examples/v3.0/uspto.yaml | 71 ++++++++++++++++++++++++++++++---------- 1 file changed, 53 insertions(+), 18 deletions(-) diff --git a/examples/v3.0/uspto.yaml b/examples/v3.0/uspto.yaml index b57439e..913db49 100644 --- a/examples/v3.0/uspto.yaml +++ b/examples/v3.0/uspto.yaml @@ -9,7 +9,16 @@ servers: - http default: https info: - description: The Data Set API (DSAPI) allows the public users to discover and search USPTO exported data sets. This is a generic API that allows USPTO users to make any CSV based data files searchable through API. With the help of GET call, it returns the list of data fields that are searchable. With the help of POST call, data can be fetched based on the filters on the field names. Please note that POST call is used to search the actual data. The reason for the POST call is that it allows users to specify any complex search criteria without worry about the GET size limitations as well as encoding of the input parameters. + description: >- + The Data Set API (DSAPI) allows the public users to discover and search + USPTO exported data sets. This is a generic API that allows USPTO users to + make any CSV based data files searchable through API. With the help of GET + call, it returns the list of data fields that are searchable. With the help + of POST call, data can be fetched based on the filters on the field names. + Please note that POST call is used to search the actual data. The reason for + the POST call is that it allows users to specify any complex search criteria + without worry about the GET size limitations as well as encoding of the + input parameters. version: 1.0.0 title: USPTO Data Set API contact: @@ -37,19 +46,19 @@ paths: $ref: '#/components/schemas/dataSetList' example: { - 'total': 2, - 'apis': [ + "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": "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', + "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", }, ], } @@ -57,8 +66,14 @@ paths: get: tags: - metadata - summary: Provides the general information about the API and the list of fields that can be used to query the dataset. - description: This GET API returns the list of all the searchable field names that are in the oa_citations. Please see the 'fields' attribute which returns an array of field names. Each field or a combination of fields can be searched using the syntax options shown below. + summary: >- + Provides the general information about the API and the list of fields + that can be used to query the dataset. + description: >- + This GET API returns the list of all the searchable field names that are + in the oa_citations. Please see the 'fields' attribute which returns an + array of field names. Each field or a combination of fields can be + searched using the syntax options shown below. operationId: list-searchable-fields parameters: - name: dataset @@ -77,13 +92,17 @@ paths: type: string responses: '200': - description: The dataset API for the given version is found and it is accessible to consume. + description: >- + The dataset API for the given version is found and it is accessible + to consume. content: application/json: schema: type: string '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. + 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. content: application/json: schema: @@ -92,8 +111,18 @@ paths: post: tags: - search - summary: Provides search capability for the data set with the given search criteria. - description: This API is based on Solr/Lucene Search. The data is indexed using SOLR. This GET API returns the list of all the searchable field names that are in the Solr Index. Please see the 'fields' attribute which returns an array of field names. Each field or a combination of fields can be searched using the Solr/Lucene Syntax. Please refer https://lucene.apache.org/core/3_6_2/queryparsersyntax.html#Overview for the query syntax. List of field names that are searchable can be determined using above GET api. + summary: >- + Provides search capability for the data set with the given search + criteria. + description: >- + This API is based on Solr/Lucene Search. The data is indexed using + SOLR. This GET API returns the list of all the searchable field names + that are in the Solr Index. Please see the 'fields' attribute which + returns an array of field names. Each field or a combination of fields + can be searched using the Solr/Lucene Syntax. Please refer + https://lucene.apache.org/core/3_6_2/queryparsersyntax.html#Overview for + the query syntax. List of field names that are searchable can be + determined using above GET api. operationId: perform-search parameters: - name: version @@ -130,7 +159,13 @@ paths: type: object properties: criteria: - description: "Uses Lucene Query Syntax in the format of propertyName:value, propertyName:[num1 TO num2] and date range format: propertyName:[yyyyMMdd TO yyyyMMdd]. In the response please see the 'docs' element which has the list of record objects. Each record structure would consist of all the fields and their corresponding values." + description: >- + Uses Lucene Query Syntax in the format of + propertyName:value, propertyName:[num1 TO num2] and date + range format: propertyName:[yyyyMMdd TO yyyyMMdd]. In the + response please see the 'docs' element which has the list of + record objects. Each record structure would consist of all + the fields and their corresponding values. type: string default: '*:*' start: From 377476a90b33acc95e1b0457369a5300dca3f069 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 16 Aug 2024 10:52:37 +0200 Subject: [PATCH 13/15] Update uspto.yaml --- examples/v3.0/uspto.yaml | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/examples/v3.0/uspto.yaml b/examples/v3.0/uspto.yaml index 913db49..3fca69e 100644 --- a/examples/v3.0/uspto.yaml +++ b/examples/v3.0/uspto.yaml @@ -52,13 +52,13 @@ paths: "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", + "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", + "apiDocumentationUrl": "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/cancer_moonshot.json" }, ], } @@ -173,7 +173,11 @@ paths: type: integer default: 0 rows: - description: Specify number of rows to be returned. If you run the search with default values, in the response you will see 'numFound' attribute which will tell the number of records available in the dataset. + description: >- + Specify number of rows to be returned. If you run the search + with default values, in the response you will see 'numFound' + attribute which will tell the number of records available in + the dataset. type: integer default: 100 required: From a548294253671e625e2e9430906c3ddb3452322e Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 16 Aug 2024 10:53:40 +0200 Subject: [PATCH 14/15] No trailing commas --- examples/v3.0/uspto.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/v3.0/uspto.yaml b/examples/v3.0/uspto.yaml index 3fca69e..9187113 100644 --- a/examples/v3.0/uspto.yaml +++ b/examples/v3.0/uspto.yaml @@ -59,8 +59,8 @@ paths: "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: From 8d257cb38565f1091790f48b6e2774309e18c220 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 21 Aug 2024 17:54:16 +0200 Subject: [PATCH 15/15] Update JSON examples and adjust workflow to use same formatter --- .../workflows/convert-examples-to-json.yaml | 3 +++ examples/v3.0/api-with-examples.json | 27 ++++++++++++++++++- package-lock.json | 16 +++++++++++ package.json | 1 + 4 files changed, 46 insertions(+), 1 deletion(-) diff --git a/.github/workflows/convert-examples-to-json.yaml b/.github/workflows/convert-examples-to-json.yaml index b0cc894..1e20d72 100644 --- a/.github/workflows/convert-examples-to-json.yaml +++ b/.github/workflows/convert-examples-to-json.yaml @@ -36,6 +36,9 @@ jobs: - name: convert YAML examples to JSON run: find examples/v3* -type f -name "*.yaml" | xargs node scripts/yaml2json/yaml2json.js + - name: pretty-print JSON examples + run: npx prettier --write examples/**/*.json + - name: git diff run: | git add examples/**/*.json diff --git a/examples/v3.0/api-with-examples.json b/examples/v3.0/api-with-examples.json index ecc992c..31d2e9b 100644 --- a/examples/v3.0/api-with-examples.json +++ b/examples/v3.0/api-with-examples.json @@ -53,7 +53,32 @@ "application/json": { "examples": { "foo": { - "value": "{\n \"versions\": [\n {\n \"status\": \"CURRENT\",\n \"updated\": \"2011-01-21T11:33:21Z\",\n \"id\": \"v2.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v2/\",\n \"rel\": \"self\"\n }\n ]\n },\n {\n \"status\": \"EXPERIMENTAL\",\n \"updated\": \"2013-07-23T11:33:21Z\",\n \"id\": \"v3.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v3/\",\n \"rel\": \"self\"\n }\n ]\n }\n ]\n}\n" + "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" + } + ] + } + ] + } } } } diff --git a/package-lock.json b/package-lock.json index 28ee457..cfa4ba0 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10,6 +10,7 @@ "license": "Apache-2.0", "dependencies": { "@hyperjump/json-schema": "^1.9.2", + "prettier": "^3.3.3", "vitest": "^1.6.0", "yaml": "^2.4.3" } @@ -1183,6 +1184,21 @@ "node": "^10 || ^12 || >=14" } }, + "node_modules/prettier": { + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.3.3.tgz", + "integrity": "sha512-i2tDNA0O5IrMO757lfrdQZCc2jPNDVntV0m/+4whiDfWaTKfMNgR7Qz0NAeGz/nRqF4m5/6CLzbP4/liHt12Ew==", + "license": "MIT", + "bin": { + "prettier": "bin/prettier.cjs" + }, + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/prettier/prettier?sponsor=1" + } + }, "node_modules/pretty-format": { "version": "29.7.0", "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-29.7.0.tgz", diff --git a/package.json b/package.json index 9dcbf1f..fec81c2 100644 --- a/package.json +++ b/package.json @@ -30,6 +30,7 @@ "homepage": "https://learn.openapis.org", "dependencies": { "@hyperjump/json-schema": "^1.9.2", + "prettier": "^3.3.3", "vitest": "^1.6.0", "yaml": "^2.4.3" }