Skip to main content

REST API docs

Find the source files​

Landing page​

Classic edition​

Vertex repo > articles > api-reference > rest-api > rest-api-landing-page.md

Cloud edition​

Currently pointing to Classic edition source files

Conceptual​

Classic edition​

Vertex repo > articles > service-docs

Cloud edition​

Currently pointing to Classic edition source files

Reference​

DocFx generates REST API docs from Swagger files in a restapi directory at the root of a docs source. Example:

articles/
builds/
restapi/
docfx.json
index.md

Classic edition​

Vertex repo

Cloud edition​

docs-template.fork.docs-infrastructure

Change the API docs​

  • To change them: Add, remove, or replace a .json file in restapi.
  • To change their order on the site: Update restapi/toc.yml.

How to get a JSON file from Swagger​

Try some form of the following. Also adjust the version. These may no longer be accurate.

Examples​

ServiceExample location
Sentry Servicehttps<nolink>://server/Sentry/swagger/ui/swagger.json
Conveyor Service V1http<nolink>://server/Conveyor/docs/V1/swagger
Conveyor Service V2https<nolink>://server/Conveyor2/swagger/ui/index
Beacon Servicehttps<nolink>://server/Beacon/swagger/swagger.json
Forge Servicehttp<nolink>://server/Forge/docs/V1/swagger
Passport Servicehttps<nolink>://server/Passport/swagger/ui/index/V1/swagger.json
Passport Directory Servicehttps<nolink>://server/PassportDirectory/swagger/ui/swagger.json
Forge Service V1https<nolink>://server/Forge/swagger/swagger.json
Forge Service V2https<nolink>://server/Forge2/swagger/swagger.json

If necessary, downgrade the JSON file from OpenAPI to Swagger 2​

Currently DocFx does not support OpenAPI.

See the api-spec-converter project on GitHub.

Write a description​

A description must be at the top of the JSON file for the landing pages to generate correctly. Example:

{
  "swagger": "2.0",
  "info": {
    "version": "swagger.json",
    "description": "The Collect database V2 stores information about source systems and data marts within the platform. Client applications can insert, update, remove, and retrieve information from the Collect database by issuing HTTP requests to Collect Service V2. Collect Service V2 has newer routes to make managing data marts easier. It uses the Passport Service.",
    "title": "Example.Collect.V2.WebService"
  }
}

For admins only​

Use scripts to add a tags object to the end of each Swagger file and generate landing pages for each API.

Troubleshoot​

See API already defined build error.