forked from eclipse-ditto/ditto
-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[eclipse-ditto#903] provide OpenAPI documentation for /cloudevents on…
… API 2 Signed-off-by: Thomas Jaeckle <[email protected]>
- Loading branch information
Showing
4 changed files
with
336 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
115 changes: 115 additions & 0 deletions
115
documentation/src/main/resources/openapi/sources/paths/cloudevents/cloudevents.yml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,115 @@ | ||
| # Copyright (c) 2020 Contributors to the Eclipse Foundation | ||
| # | ||
| # See the NOTICE file(s) distributed with this work for additional | ||
| # information regarding copyright ownership. | ||
| # | ||
| # This program and the accompanying materials are made available under the | ||
| # terms of the Eclipse Public License 2.0 which is available at | ||
| # http://www.eclipse.org/legal/epl-2.0 | ||
| # | ||
| # SPDX-License-Identifier: EPL-2.0 | ||
| post: | ||
| summary: Processes a CloudEvent sent in Ditto Protocol | ||
| description: |- | ||
| Provides an endpoint accepting [CloudEvents via its HTTP protocol binding](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md) | ||
| in [Ditto Protocol JSON](https://www.eclipse.org/ditto/protocol-specification.html). | ||
| The endpoint can also directly be configured as a [Knative eventing](https://knative.dev/docs/eventing/) destination. | ||
| Find more documentation on that [here](https://www.eclipse.org/ditto/httpapi-protocol-bindings-cloudevents.html). | ||
| tags: | ||
| - CloudEvents | ||
| parameters: | ||
| - in: header | ||
| name: ce-specversion | ||
| description: The CloudEvents "specversion". | ||
| schema: | ||
| type: string | ||
| example: "1.0" | ||
| required: true | ||
| - in: header | ||
| name: ce-type | ||
| description: The CloudEvents event "type". | ||
| schema: | ||
| type: string | ||
| example: "com.example.someevent" | ||
| required: true | ||
| - in: header | ||
| name: ce-source | ||
| description: The CloudEvents event "source". | ||
| schema: | ||
| type: string | ||
| example: "/mycontext" | ||
| required: true | ||
| - in: header | ||
| name: ce-id | ||
| description: The CloudEvents event "id". | ||
| schema: | ||
| type: string | ||
| example: "1234-1234-1234" | ||
| required: true | ||
| - in: header | ||
| name: ce-time | ||
| description: The CloudEvents event "time". | ||
| schema: | ||
| type: string | ||
| format: date-time | ||
| example: "2020-12-31T23:59:59Z" | ||
| required: true | ||
| - in: header | ||
| name: ce-dataschema | ||
| description: The CloudEvents event "dataschema". If provided, this must start with `ditto:`. | ||
| schema: | ||
| type: string | ||
| required: false | ||
| responses: | ||
| '202': | ||
| description: |- | ||
| The Ditto Protocol CloudEvent was successfully parsed, the authentication was valid and also reached the persistence. | ||
| '400': | ||
| description: |- | ||
| The request could not be completed. Possible reasons: | ||
| * the CloudEvent could not be parsed as some mandatory CloudEvent headers were missing from the request | ||
| * the payload was missing from the CloudEvent | ||
| * the [Ditto Protocol JSON](https://www.eclipse.org/ditto/protocol-specification.html) message could not be parsed or was missing a required field | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '../../schemas/advancedError.yml' | ||
| '401': | ||
| description: The request could not be completed due to missing authentication. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '../../schemas/advancedError.yml' | ||
| '403': | ||
| description: |- | ||
| The request could not be completed. Possible reasons: | ||
| * the caller has insufficient permissions. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '../../schemas/advancedError.yml' | ||
| '404': | ||
| description: |- | ||
| The request could not be completed. Possible reasons: | ||
| * the referenced thing does not exist. | ||
| * the caller has insufficient permissions to perform the contained Ditto Protocol command. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '../../schemas/advancedError.yml' | ||
| '408': | ||
| description: The request could not be completed due to timeout. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '../../schemas/advancedError.yml' | ||
| '415': | ||
| description: The `Content-Type` of the request was not supported. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '../../schemas/advancedError.yml' | ||
| requestBody: | ||
| $ref: '../../requests/dittoProtocol.yml' |
60 changes: 60 additions & 0 deletions
60
documentation/src/main/resources/openapi/sources/requests/dittoProtocol.yml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| # Copyright (c) 2020 Contributors to the Eclipse Foundation | ||
| # | ||
| # See the NOTICE file(s) distributed with this work for additional | ||
| # information regarding copyright ownership. | ||
| # | ||
| # This program and the accompanying materials are made available under the | ||
| # terms of the Eclipse Public License 2.0 which is available at | ||
| # http://www.eclipse.org/legal/epl-2.0 | ||
| # | ||
| # SPDX-License-Identifier: EPL-2.0 | ||
| content: | ||
| application/vnd.eclipse.ditto+json: | ||
| schema: | ||
| type: object | ||
| properties: | ||
| topic: | ||
| type: string | ||
| description: |- | ||
| Contains information about the contents of the payload: | ||
| * the affected Thing (namespace and Thing ID) | ||
| * the type of operation (command/event, create/retrieve/modify/delete) | ||
| example: "org.eclipse.ditto/thing-1/things/twin/commands/modify" | ||
| headers: | ||
| type: object | ||
| description: Additional headers. | ||
| properties: | ||
| correlation-id: | ||
| type: string | ||
| description: |- | ||
| The correlation-id header is used for linking one message with another. | ||
| It typically links a reply message with its requesting message. | ||
| example: | ||
| correlation-id: "1234-4321-1234" | ||
| path: | ||
| type: string | ||
| description: References the part of a Thing which is affected by this message. | ||
| example: "/features/location/properties/longitude" | ||
| value: | ||
| oneOf: | ||
| - type: "object" | ||
| - type: "string" | ||
| - type: "number" | ||
| - type: "array" | ||
| - type: "boolean" | ||
| description: The `value` field contains the actual payload e.g. a sensor value. | ||
| required: | ||
| - topic | ||
| - path | ||
| example: { | ||
| "topic": "org.eclipse.ditto/thing-1/things/twin/commands/modify", | ||
| "path": "/", | ||
| "value": { | ||
| "attributes": { | ||
| "foo": 42 | ||
| } | ||
| } | ||
| } | ||
| description: |- | ||
| The [Ditto Protocol JSON](https://www.eclipse.org/ditto/protocol-specification.html) payload defining which | ||
| command to process. |