openapi-schemas

OpenAPI 3.0 JSON schemas. Files are automatically synced the VTEX Developer Portal API Reference page and can be imported to Postman following these instructions.

VTEX APIs Here:

Antifraud Provider API
Catalog API
Checkout API
CMS - Change URI Schema
Customer Credit API
GiftCard Hub API
GiftCard API
GiftCard Provider Protocol
License Manager API
Logistics API
Marketplace APIs
Marketplace Protocol
Master Data API - v1
Master Data API - v2
Orders API
Payment Provider Protocol
Payments Gateway API
Policies System API
Price Simulations API
Pricing API
Pricing Hub
Promotions & Taxes API
Recurrence (v1 - deprecated)
Search API
Session Manager API
Subscriptions (v2 - deprecated)
Subscriptions (v3)
Tracking 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/github-readme-sync@1.0.1
  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.

CaDevecchi/openapi-schemas