openapi-schemas

OpenApi 3.0 json schemas. Files are automatically synced to the developer docs pages

VTEX APIs Here:

• Catalog API
• Checkout API
• CMS - Change URI Schema
• Customer Credit API
• GiftCard System API
• GiftCard Hub API
• GiftCard API
• GiftCard Provider Protocol
• License Manager API
• Logistics API
• Master Data API - v1
• Master Data API - v2
• Orders API
• Payment Provider Protocol
• Payments Gateway API
• Pricing API
• Rates and Benefits API
• Recurrence (v1 - deprecated)
• Search API
• Session Manager API
• Subscriptions (v2)
• Suggestions API
• VTEX Do API

Schema files

• The files should follow the JSON OpenApi 3.0 format Specification
• Schema files shoud have a mnemonic file name that specifies the API being described
• VTEX_TEMPLATE.json is an example of a simple api. It shows how to represent endpoints and parameters. Also all server and auth configuration are as they should be for VTEX APIs.

Sync Automation

To get schema files to sync with our developer docs, they should be described at .github\workflows\readme-github-sync.yml.

Add this code to the action description to sync a new file:

- name: Sync ____________ API #Replace with API title
  uses: readmeio/[email protected]
  with:
    # The GITHUB_TOKEN secret
    repo-token: '${{ secrets.GITHUB_TOKEN }}' #Do not change
    # The path for your API spec file
    api-file-path: # .json files should be in the root folder
    # Your API key for your ReadMe project
    readme-api-key: ${{ secrets.README_API_KEY }} #Do not change
    # ID for the API Setting in ReadMe - you can get that from the dashboard
    readme-api-id: # optional
    # ReadMe version to sync API into
    readme-api-version: # optional

Important Schema Details:

Server

OpenApi describes the full endpoint for accessing the API as {Server URL} + {endpoint Path} + {Path Parameters}. So a endpoint with /api/getResults as path in a schema with https://example.com as the url in the server object and no parameters will tell clients to send requests to https://example.com/api/getResults

Server Object Example:

"servers": [
    {
        "url": "https://{accountName}.{environment}.com.br",
        "description": "VTEX server url",
        "variables": {
            "accountName": {
                "default": "apiexamples",
                "description": "Your VTEX account name"
            },
            "environment": {
                "enum": [
                    "vtexcommercestable",
                    "myvtex"
                ],
                "default": "vtexcommercestable"
            }
        }
    }
],

The servers key contains an array of server objects. But Readme.io, our documentation system, will select the first one and use default values for the variables

Authentication

Security Scheme

Security schemes describe autentication types that are available in this API. you can check the all the options available int the Security Scheme Spec

They should be inserted inside the Components Object

the ones we use for VTEX appKey and appToken are:

"securitySchemes": {
    "appKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-VTEX-API-AppKey"
    },
    "appToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-VTEX-API-AppToken"
    }
}

This tells the client that the request should have X-VTEX-API-AppKey and X-VTEX-API-AppToken as variables in the request header

Security Requirement

If defined inside the Open API Object the security requirement will define the required security schemes for all endpoints. If defined inside a path object, it will define a per-endpoint security scheme.

The example we are currently using, defined inside the Open API Object, is:

"security": [
        {
            "appKey": [],
            "appToken": []
        }
    ]

Examples

Example objects will be ignored by our documentation generator. If the desired outcome is to have the values as placeholders in the request parameters form, they should be inside the parameter schema object in the default key.