Create API docs with the REST API

Each API on Skmtc Hub has a docs page. This page tells you how to make an API from an OpenAPI document with one request. The response gives the address of the docs page. You do not choose an account or a slug.

Create a tokenCopy Anchor Link

1. Open Settings → Access tokens.
2. Make a new token. Give it a name and an expiration, and select publish:schemas.
3. Copy the secret. Skmtc shows it one time only.
4. Put the secret in SKMTC_HUB_TOKEN in your shell.

Send a fileCopy Anchor Link

Send the raw OpenAPI JSON or YAML document to POST /v1/apis/publish:

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $SKMTC_HUB_TOKEN" \
  --header 'Content-Type: application/octet-stream' \
  --data-binary @openapi.yaml \
  'https://api.skmtc.dev/v1/apis/publish?visibility=private&filename=openapi.yaml'

The file can be up to 50 MB.

Send a URLCopy Anchor Link

When the document is on the web, send its URL to POST /v1/apis/publish/import. Skmtc gets the document from that URL:

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $SKMTC_HUB_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://example.com/openapi.json", "visibility": "private"}' \
  'https://api.skmtc.dev/v1/apis/publish/import'

The URL can be a direct link to the document, or a file on GitHub or GitLab. When you send the same URL again and the document has changed, Skmtc adds a revision to the API that it made from that URL. When the document has not changed, the response has that API with deduped: true.

Open the docs pageCopy Anchor Link

The response has docsUrl, the address of the docs page of the API:

{
  "api": { "slug": "billing", "visibility": "private" },
  "isNewApi": true,
  "deduped": false,
  "docsUrl": "https://skmtc.dev/ada/apis/billing"
}

The example shows only some of the fields of the response.

What Skmtc chooses for youCopy Anchor Link

• Account. The API goes in your own account. To put it in an organization that you are a member of, add owner with the handle of the organization.
• Slug. Skmtc makes the slug from the info.title of the document. When you already have an API with that slug, Skmtc adds a number, for example billing-2. To choose the slug, add slug.
• Visibility. You must send visibility. Send private to make an API that only you, or the members of the organization, can see. Send public to show it to all readers.

When you send a file that has the same bytes as one of your APIs, Skmtc makes no new API. The response has that API, with deduped: true. The visibility that you send must be the visibility of that API. If it is not, the response is 409.

When you send a URL that one of your APIs already has, the response has that API, whatever visibility you send. Skmtc uses visibility only for a new API.

To add a revision to an API that exists, name it with owner and slug. See Publish an API.