mirror of
https://github.com/gcatanese/adyen-openapi.git
synced 2026-03-10 08:01:24 +00:00
94 lines
3.6 KiB
Markdown
94 lines
3.6 KiB
Markdown
# Adyen OpenAPI / Swagger definitions
|
||
|
||
Adyen provides [various APIs](https://docs.adyen.com) to help you accept payments on your website or mobile application, implement subscription billing, make payouts, and much more.
|
||
|
||
This repository contains Adyen API definition files, represented in the [OpenAPI Specification](https://www.openapis.org/) standard (formerly known as Swagger Specification).
|
||
|
||
## Folder structure
|
||
|
||
API definitions in this repository are organized into two sub-folders:
|
||
|
||
```
|
||
/json – Definition files in the json format.
|
||
/yaml – Definition files in the yaml format.
|
||
```
|
||
|
||
We support the OpenAPI version 3.1.0.
|
||
|
||
## Usage
|
||
|
||
There are multiple ways you can use the OpenAPI definition to explore the Adyen API:
|
||
- If you want to see the API definitions in action, visit the [Adyen API Explorer](https://docs.adyen.com/api-explorer/) portal.
|
||
- If you prefer to use the classic Swagger toolset, upload these definitions to the [Swagger Editor](http://editor.swagger.io/) or [SwaggerHub](https://swaggerhub.com/).
|
||
- Also, we recommend you use [Postman](https://www.getpostman.com/postman) to import the API definition and create your personal collection of requests.
|
||
|
||
## Vendor extensions
|
||
|
||
Adyen's API definitions contain some custom extensions, as [allowed by the OpenAPI standard](https://swagger.io/docs/specification/openapi-extensions/). These are extensions that provide metadata, such as the grouping and sort order of API objects, when they are displayed in the [Adyen API Explorer](https://docs.adyen.com/api-explorer/).
|
||
|
||
### x-groups
|
||
|
||
This extension provides a list of all endpoint groups for the selected API.
|
||
|
||
For example:
|
||
|
||
``` yaml
|
||
x-groups:
|
||
- General
|
||
- Modifications
|
||
```
|
||
|
||
### x-groupName and x-sortIndex
|
||
|
||
These extensions specify how to group endpoints and sort them within a group.
|
||
|
||
For example:
|
||
|
||
``` yaml
|
||
paths:
|
||
...
|
||
post:
|
||
...
|
||
x-groupName: Modifications
|
||
x-sortIndex: 5
|
||
...
|
||
```
|
||
|
||
### x-publicVersion
|
||
|
||
This is an auxiliary extension that helps us verify that the current API version is publicly available.
|
||
|
||
### x-addedInVersion, x-deprecatedInVersion and x-deprecatedMessage
|
||
|
||
These extensions help us add information when a certain endpoint or field has been added, and later when they are deprecated.
|
||
|
||
In addition, the `x-deprecatedMessage` can contain a human-readable message explaining what to use instead of a deprecated API, which provides much better developer experience:
|
||
|
||
``` yaml
|
||
recurringDetailReference:
|
||
deprecated: true
|
||
x-deprecatedInVersion: 49
|
||
x-deprecatedMessage: Use `storedPaymentMethodId` instead.
|
||
description: This is the `recurringDetailReference` returned in the response when you created the token.
|
||
type: string
|
||
storedPaymentMethodId:
|
||
x-addedInVersion: 49
|
||
description: This is the `recurringDetailReference` returned in the response when you created the token.
|
||
type: string
|
||
```
|
||
|
||
### x-oneOf, x-anyOf, x-not and x-allOf
|
||
|
||
These extensions are equivalent to those from the [JSON Schema](https://json-schema.org/understanding-json-schema/reference/combining.html) but don't enforce strict validation.
|
||
|
||
We use them in some rare cases when we need to avoid validation issues with open-source tooling, while still being able to display this information in our [API Explorer](https://docs.adyen.com/api-explorer/).
|
||
|
||
## Support
|
||
|
||
If you have a feature request, or spotted a bug or a technical problem, create a GitHub issue. For other questions, contact our [Team](https://www.adyen.help/hc/en-us/requests/new).
|
||
|
||
## License
|
||
|
||
This repository is open source and available under the MIT license. For more information, see the LICENSE file.
|
||
|