Skip to content

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

Notifications You must be signed in to change notification settings

JulianaMeyerArruda/openapi-schemas

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

openapi-schemas

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

VTEX APIs Here:

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

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.

About

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

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published