diff --git a/compliant-sets/README.md b/compliant-sets/README.md new file mode 100644 index 0000000..77d34b0 --- /dev/null +++ b/compliant-sets/README.md @@ -0,0 +1,9 @@ +# OpenAPI Overlay Compliant Sets + +The folders in this directory contain sets of "known good" Overlays, along with OpenAPI descriptions before and after the Overlay. +These files are offered as examples of how a series of Overlays are expected to be applied, with the aim of supporting people building tools that apply Overlays. + +Each directory contains: +- `overlay.yaml` - the Overlay +- `openapi.yaml` - an OpenAPI description to use +- `output.yaml` - the OpenAPI description after the Overlay has been applied diff --git a/compliant-sets/add-a-license/openapi.yaml b/compliant-sets/add-a-license/openapi.yaml new file mode 100644 index 0000000..12a99c1 --- /dev/null +++ b/compliant-sets/add-a-license/openapi.yaml @@ -0,0 +1,70 @@ +openapi: 3.1.0 +info: + version: 1.0.0 + title: Imaginary town +servers: + - url: 'https://example.com' + description: Example server +paths: + /buildings: + get: + summary: All buildings + operationId: buildingsList + responses: + '200': + description: Return all known buildings + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Building' + '/buildings/{buildingId}': + get: + summary: Specific building + operationId: buildingById + parameters: + - name: buildingId + in: path + required: true + description: Which building to return + schema: + type: string + responses: + '200': + description: Return a building + content: + application/json: + schema: + $ref: '#/components/schemas/Building' + /locations: + get: + summary: All locations + operationId: locationList + responses: + '200': + description: Returns all locations + content: + application/json: + schema: + type: array + items: + type: object + properties: + location_id: + type: integer + example: 44 + name: + type: string + example: North Village +components: + schemas: + Building: + type: object + properties: + building: + type: string + example: house + location_id: + type: integer + example: 44 diff --git a/compliant-sets/add-a-license/output.yaml b/compliant-sets/add-a-license/output.yaml new file mode 100644 index 0000000..8378332 --- /dev/null +++ b/compliant-sets/add-a-license/output.yaml @@ -0,0 +1,74 @@ +openapi: 3.1.0 +info: + version: 1.0.0 + title: Imaginary town + license: + name: MIT + url: 'https://opensource.org/licenses/MIT' +servers: + - url: 'https://example.com' + description: Example server +paths: + /buildings: + get: + summary: All buildings + operationId: buildingsList + responses: + '200': + description: Return all known buildings + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Building' + '/buildings/{buildingId}': + get: + summary: Specific building + operationId: buildingById + parameters: + - name: buildingId + in: path + required: true + description: Which building to return + schema: + type: string + responses: + '200': + description: Return a building + content: + application/json: + schema: + $ref: '#/components/schemas/Building' + /locations: + get: + summary: All locations + operationId: locationList + responses: + '200': + description: Returns all locations + content: + application/json: + schema: + type: array + items: + type: object + properties: + location_id: + type: integer + example: 44 + name: + type: string + example: North Village +components: + schemas: + Building: + type: object + properties: + building: + type: string + example: house + location_id: + type: integer + example: 44 + diff --git a/compliant-sets/add-a-license/overlay.yaml b/compliant-sets/add-a-license/overlay.yaml new file mode 100644 index 0000000..3fea356 --- /dev/null +++ b/compliant-sets/add-a-license/overlay.yaml @@ -0,0 +1,10 @@ +overlay: '1.0.0' +info: + title: Add MIT license + version: '1.0.0' +actions: + - target: '$.info' + update: + license: + name: MIT + url: https://opensource.org/licenses/MIT diff --git a/compliant-sets/description-and-summary/openapi.yaml b/compliant-sets/description-and-summary/openapi.yaml new file mode 100644 index 0000000..12a99c1 --- /dev/null +++ b/compliant-sets/description-and-summary/openapi.yaml @@ -0,0 +1,70 @@ +openapi: 3.1.0 +info: + version: 1.0.0 + title: Imaginary town +servers: + - url: 'https://example.com' + description: Example server +paths: + /buildings: + get: + summary: All buildings + operationId: buildingsList + responses: + '200': + description: Return all known buildings + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Building' + '/buildings/{buildingId}': + get: + summary: Specific building + operationId: buildingById + parameters: + - name: buildingId + in: path + required: true + description: Which building to return + schema: + type: string + responses: + '200': + description: Return a building + content: + application/json: + schema: + $ref: '#/components/schemas/Building' + /locations: + get: + summary: All locations + operationId: locationList + responses: + '200': + description: Returns all locations + content: + application/json: + schema: + type: array + items: + type: object + properties: + location_id: + type: integer + example: 44 + name: + type: string + example: North Village +components: + schemas: + Building: + type: object + properties: + building: + type: string + example: house + location_id: + type: integer + example: 44 diff --git a/compliant-sets/description-and-summary/output.yaml b/compliant-sets/description-and-summary/output.yaml new file mode 100644 index 0000000..4394d8f --- /dev/null +++ b/compliant-sets/description-and-summary/output.yaml @@ -0,0 +1,71 @@ +openapi: 3.1.0 +info: + version: 1.0.0 + title: Imaginary town +servers: + - url: 'https://example.com' + description: Example server +paths: + /buildings: + get: + summary: All of the available buildings + operationId: buildingsList + description: This is the summary of getting the buildings + responses: + '200': + description: Return all known buildings + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Building' + '/buildings/{buildingId}': + get: + summary: Specific building + operationId: buildingById + parameters: + - name: buildingId + in: path + required: true + description: Which building to return + schema: + type: string + responses: + '200': + description: Return a building + content: + application/json: + schema: + $ref: '#/components/schemas/Building' + /locations: + get: + summary: All locations + operationId: locationList + responses: + '200': + description: Returns all locations + content: + application/json: + schema: + type: array + items: + type: object + properties: + location_id: + type: integer + example: 44 + name: + type: string + example: North Village +components: + schemas: + Building: + type: object + properties: + building: + type: string + example: house + location_id: + type: integer + example: 44 diff --git a/compliant-sets/description-and-summary/overlay.yaml b/compliant-sets/description-and-summary/overlay.yaml new file mode 100644 index 0000000..36fb1cb --- /dev/null +++ b/compliant-sets/description-and-summary/overlay.yaml @@ -0,0 +1,10 @@ +overlay: 1.0.0 +info: + title: Add a building endpoint description + version: 1.0.0 +actions: +- target: $.paths['/buildings'].get + update: + description: This is the summary of getting the buildings + summary: All of the available buildings + diff --git a/compliant-sets/remove-example/openapi.yaml b/compliant-sets/remove-example/openapi.yaml new file mode 100644 index 0000000..12a99c1 --- /dev/null +++ b/compliant-sets/remove-example/openapi.yaml @@ -0,0 +1,70 @@ +openapi: 3.1.0 +info: + version: 1.0.0 + title: Imaginary town +servers: + - url: 'https://example.com' + description: Example server +paths: + /buildings: + get: + summary: All buildings + operationId: buildingsList + responses: + '200': + description: Return all known buildings + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Building' + '/buildings/{buildingId}': + get: + summary: Specific building + operationId: buildingById + parameters: + - name: buildingId + in: path + required: true + description: Which building to return + schema: + type: string + responses: + '200': + description: Return a building + content: + application/json: + schema: + $ref: '#/components/schemas/Building' + /locations: + get: + summary: All locations + operationId: locationList + responses: + '200': + description: Returns all locations + content: + application/json: + schema: + type: array + items: + type: object + properties: + location_id: + type: integer + example: 44 + name: + type: string + example: North Village +components: + schemas: + Building: + type: object + properties: + building: + type: string + example: house + location_id: + type: integer + example: 44 diff --git a/compliant-sets/remove-example/output.yaml b/compliant-sets/remove-example/output.yaml new file mode 100644 index 0000000..24bfdd6 --- /dev/null +++ b/compliant-sets/remove-example/output.yaml @@ -0,0 +1,69 @@ +openapi: 3.1.0 +info: + version: 1.0.0 + title: Imaginary town +servers: + - url: 'https://example.com' + description: Example server +paths: + /buildings: + get: + summary: All buildings + operationId: buildingsList + responses: + '200': + description: Return all known buildings + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Building' + '/buildings/{buildingId}': + get: + summary: Specific building + operationId: buildingById + parameters: + - name: buildingId + in: path + required: true + description: Which building to return + schema: + type: string + responses: + '200': + description: Return a building + content: + application/json: + schema: + $ref: '#/components/schemas/Building' + /locations: + get: + summary: All locations + operationId: locationList + responses: + '200': + description: Returns all locations + content: + application/json: + schema: + type: array + items: + type: object + properties: + location_id: + type: integer + example: 44 + name: + type: string + example: North Village +components: + schemas: + Building: + type: object + properties: + building: + type: string + location_id: + type: integer + example: 44 diff --git a/compliant-sets/remove-example/overlay.yaml b/compliant-sets/remove-example/overlay.yaml new file mode 100644 index 0000000..5963349 --- /dev/null +++ b/compliant-sets/remove-example/overlay.yaml @@ -0,0 +1,7 @@ +overlay: 1.0.0 +info: + title: Remove an example + version: 1.0.0 +actions: +- target: $.components.schemas.Building.properties['building'].example + remove: true diff --git a/compliant-sets/remove-matching-responses/openapi.yaml b/compliant-sets/remove-matching-responses/openapi.yaml new file mode 100644 index 0000000..8d260cc --- /dev/null +++ b/compliant-sets/remove-matching-responses/openapi.yaml @@ -0,0 +1,30 @@ +openapi: 3.1.0 +info: + title: Responses + version: 1.0.0 +paths: + /foo: + get: + responses: + '200': + description: OK + '500': + description: oops + /bar: + post: + responses: + '201': + description: Created + '500': + description: oops + default: + description: something + /baa: + post: + responses: + '201': + description: Shouted + '500': + description: oops + default: + description: something diff --git a/compliant-sets/remove-matching-responses/output.yaml b/compliant-sets/remove-matching-responses/output.yaml new file mode 100644 index 0000000..ac5444b --- /dev/null +++ b/compliant-sets/remove-matching-responses/output.yaml @@ -0,0 +1,20 @@ +openapi: 3.1.0 +info: + title: Responses + version: 1.0.0 +paths: + /foo: + get: + responses: + '200': + description: OK + /bar: + post: + responses: + '201': + description: Created + /baa: + post: + responses: + '201': + description: Shouted diff --git a/compliant-sets/remove-matching-responses/overlay.yaml b/compliant-sets/remove-matching-responses/overlay.yaml new file mode 100644 index 0000000..6607a77 --- /dev/null +++ b/compliant-sets/remove-matching-responses/overlay.yaml @@ -0,0 +1,11 @@ +overlay: 1.0.0 +info: + title: Response code removal test + version: 1.0.0 + +actions: + - target: $.paths..responses['500'] + remove: true + + - target: $.paths..responses['default'] + remove: true diff --git a/compliant-sets/remove-property/openapi.yaml b/compliant-sets/remove-property/openapi.yaml new file mode 100644 index 0000000..12a99c1 --- /dev/null +++ b/compliant-sets/remove-property/openapi.yaml @@ -0,0 +1,70 @@ +openapi: 3.1.0 +info: + version: 1.0.0 + title: Imaginary town +servers: + - url: 'https://example.com' + description: Example server +paths: + /buildings: + get: + summary: All buildings + operationId: buildingsList + responses: + '200': + description: Return all known buildings + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Building' + '/buildings/{buildingId}': + get: + summary: Specific building + operationId: buildingById + parameters: + - name: buildingId + in: path + required: true + description: Which building to return + schema: + type: string + responses: + '200': + description: Return a building + content: + application/json: + schema: + $ref: '#/components/schemas/Building' + /locations: + get: + summary: All locations + operationId: locationList + responses: + '200': + description: Returns all locations + content: + application/json: + schema: + type: array + items: + type: object + properties: + location_id: + type: integer + example: 44 + name: + type: string + example: North Village +components: + schemas: + Building: + type: object + properties: + building: + type: string + example: house + location_id: + type: integer + example: 44 diff --git a/compliant-sets/remove-property/output.yaml b/compliant-sets/remove-property/output.yaml new file mode 100644 index 0000000..aaf6e0c --- /dev/null +++ b/compliant-sets/remove-property/output.yaml @@ -0,0 +1,67 @@ +openapi: 3.1.0 +info: + version: 1.0.0 + title: Imaginary town +servers: + - url: 'https://example.com' + description: Example server +paths: + /buildings: + get: + summary: All buildings + operationId: buildingsList + responses: + '200': + description: Return all known buildings + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Building' + '/buildings/{buildingId}': + get: + summary: Specific building + operationId: buildingById + parameters: + - name: buildingId + in: path + required: true + description: Which building to return + schema: + type: string + responses: + '200': + description: Return a building + content: + application/json: + schema: + $ref: '#/components/schemas/Building' + /locations: + get: + summary: All locations + operationId: locationList + responses: + '200': + description: Returns all locations + content: + application/json: + schema: + type: array + items: + type: object + properties: + location_id: + type: integer + example: 44 +components: + schemas: + Building: + type: object + properties: + building: + type: string + example: house + location_id: + type: integer + example: 44 diff --git a/compliant-sets/remove-property/overlay.yaml b/compliant-sets/remove-property/overlay.yaml new file mode 100644 index 0000000..e143719 --- /dev/null +++ b/compliant-sets/remove-property/overlay.yaml @@ -0,0 +1,8 @@ +overlay: 1.0.0 +info: + title: Remove all string properties + version: 1.0.0 +actions: +- target: $.paths['/locations'].get.responses['200']..properties[?(@.type == 'string')] + remove: true + diff --git a/compliant-sets/remove-server/openapi.yaml b/compliant-sets/remove-server/openapi.yaml new file mode 100644 index 0000000..9187ea5 --- /dev/null +++ b/compliant-sets/remove-server/openapi.yaml @@ -0,0 +1,10 @@ +openapi: 3.1.0 +info: + title: API servers + version: 1.0.0 +servers: + - url: 'https://api.dev.example.com' + description: Dev + - url: 'https://api.example.com' + description: Production +paths: {} diff --git a/compliant-sets/remove-server/output.yaml b/compliant-sets/remove-server/output.yaml new file mode 100644 index 0000000..8195aea --- /dev/null +++ b/compliant-sets/remove-server/output.yaml @@ -0,0 +1,8 @@ +openapi: 3.1.0 +info: + title: API servers + version: 1.0.0 +servers: + - url: 'https://api.example.com' + description: Production +paths: {} diff --git a/compliant-sets/remove-server/overlay.yaml b/compliant-sets/remove-server/overlay.yaml new file mode 100644 index 0000000..aa3a050 --- /dev/null +++ b/compliant-sets/remove-server/overlay.yaml @@ -0,0 +1,9 @@ +overlay: 1.0.0 +info: + title: Remove dev server + version: 1.0.0 +extends: openapi-with-servers.yaml + +actions: + - target: $.servers[?( @.description == 'Dev' )] + remove: true diff --git a/compliant-sets/replace-servers-for-sandbox/openapi.yaml b/compliant-sets/replace-servers-for-sandbox/openapi.yaml new file mode 100644 index 0000000..e514c5b --- /dev/null +++ b/compliant-sets/replace-servers-for-sandbox/openapi.yaml @@ -0,0 +1,46 @@ +openapi: 3.1.0 +info: + title: Simple API + description: A basic OpenAPI description with a single endpoint. + version: 1.0.0 +servers: + - url: https://api.example.com/v1 + description: Production server + - url: https://staging.example.com/v1 + description: Staging server +paths: + /getItems: + get: + summary: Retrieve a list of items + description: Fetch a list of items from the API. + operationId: getItems + responses: + '200': + description: Successful response with items + content: + application/json: + schema: + type: array + items: + type: object + properties: + id: + type: integer + description: Unique identifier for the item + name: + type: string + description: Name of the item + description: + type: string + description: Detailed information about the item + examples: + example1: + summary: Example response + value: + - id: 1 + name: Item One + description: Description for item one + - id: 2 + name: Item Two + description: Description for item two + diff --git a/compliant-sets/replace-servers-for-sandbox/output.yaml b/compliant-sets/replace-servers-for-sandbox/output.yaml new file mode 100644 index 0000000..e354868 --- /dev/null +++ b/compliant-sets/replace-servers-for-sandbox/output.yaml @@ -0,0 +1,43 @@ +openapi: 3.1.0 +info: + title: Simple API + description: A basic OpenAPI description with a single endpoint. + version: 1.0.0 +paths: + /getItems: + get: + summary: Retrieve a list of items + description: Fetch a list of items from the API. + operationId: getItems + responses: + '200': + description: Successful response with items + content: + application/json: + schema: + type: array + items: + type: object + properties: + id: + type: integer + description: Unique identifier for the item + name: + type: string + description: Name of the item + description: + type: string + description: Detailed information about the item + examples: + example1: + summary: Example response + value: + - id: 1 + name: Item One + description: Description for item one + - id: 2 + name: Item Two + description: Description for item two +servers: + - url: http://api-test-tunnel.local + description: Local development server diff --git a/compliant-sets/replace-servers-for-sandbox/overlay.yaml b/compliant-sets/replace-servers-for-sandbox/overlay.yaml new file mode 100644 index 0000000..dd1ffde --- /dev/null +++ b/compliant-sets/replace-servers-for-sandbox/overlay.yaml @@ -0,0 +1,13 @@ +overlay: 1.0.0 +info: + title: Change server URL + description: Replace servers list with a single sandbox or local development URL for the API + version: 1.0.0 +actions: + - target: '$.servers' + remove: true + - target: '$' + update: + servers: + - url: http://api-test-tunnel.local + description: Local development server \ No newline at end of file diff --git a/compliant-sets/update-root/openapi.yaml b/compliant-sets/update-root/openapi.yaml new file mode 100644 index 0000000..12a99c1 --- /dev/null +++ b/compliant-sets/update-root/openapi.yaml @@ -0,0 +1,70 @@ +openapi: 3.1.0 +info: + version: 1.0.0 + title: Imaginary town +servers: + - url: 'https://example.com' + description: Example server +paths: + /buildings: + get: + summary: All buildings + operationId: buildingsList + responses: + '200': + description: Return all known buildings + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Building' + '/buildings/{buildingId}': + get: + summary: Specific building + operationId: buildingById + parameters: + - name: buildingId + in: path + required: true + description: Which building to return + schema: + type: string + responses: + '200': + description: Return a building + content: + application/json: + schema: + $ref: '#/components/schemas/Building' + /locations: + get: + summary: All locations + operationId: locationList + responses: + '200': + description: Returns all locations + content: + application/json: + schema: + type: array + items: + type: object + properties: + location_id: + type: integer + example: 44 + name: + type: string + example: North Village +components: + schemas: + Building: + type: object + properties: + building: + type: string + example: house + location_id: + type: integer + example: 44 diff --git a/compliant-sets/update-root/output.yaml b/compliant-sets/update-root/output.yaml new file mode 100644 index 0000000..22fbe70 --- /dev/null +++ b/compliant-sets/update-root/output.yaml @@ -0,0 +1,71 @@ +openapi: 3.1.0 +info: + version: 1.0.0 + title: Imaginary town + x-overlaid: true +servers: + - url: 'https://example.com' + description: Example server +paths: + /buildings: + get: + summary: All buildings + operationId: buildingsList + responses: + '200': + description: Return all known buildings + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Building' + '/buildings/{buildingId}': + get: + summary: Specific building + operationId: buildingById + parameters: + - name: buildingId + in: path + required: true + description: Which building to return + schema: + type: string + responses: + '200': + description: Return a building + content: + application/json: + schema: + $ref: '#/components/schemas/Building' + /locations: + get: + summary: All locations + operationId: locationList + responses: + '200': + description: Returns all locations + content: + application/json: + schema: + type: array + items: + type: object + properties: + location_id: + type: integer + example: 44 + name: + type: string + example: North Village +components: + schemas: + Building: + type: object + properties: + building: + type: string + example: house + location_id: + type: integer + example: 44 diff --git a/compliant-sets/update-root/overlay.yaml b/compliant-sets/update-root/overlay.yaml new file mode 100644 index 0000000..606ec8f --- /dev/null +++ b/compliant-sets/update-root/overlay.yaml @@ -0,0 +1,9 @@ +overlay: 1.0.0 +info: + title: Structured Overlay + version: 1.0.0 +actions: +- target: "$" # Root of document + update: + info: + x-overlaid: true