Skip to content

openapi.md

Latest commit

 

History

History
280 lines (233 loc) · 6.34 KB

openapi.md

File metadata and controls

280 lines (233 loc) · 6.34 KB

OpenAPI Specification

We're expecting the passed OpenAPI document to adhere to the Swagger 2.0, OpenAPI 3.0 or OpenAPI 3.1 specification.

On top of that, we've added a few things for your convenience:

Custom Specification Extensions

You can add custom specification extensions (starting with a x-) through our plugin API.

x-scalar-environments

You can specify predefined environment variables for the API Client/References to consume and use:

x-scalar-environments:
  production:
    description: "Production environment"
    color: "#0082D0"
    # Variables are saved directly to the specification
    variables:
      userId:
        description: "User ID"
        default: "1234567890"
      apiUrl:
        description: "API URL"
        default: "https://api.production.example.com"
  staging:
    description: "Staging environment"
    variables:
      userId: "1234567890"
      apiUrl:
        description: "API URL"
        default: "https://api.staging.example.com"

x-scalar-active-environment

You can also specify the default active environment a user will have :) if there's none set here we pick the first from the x-scalar-environments to be the default

x-scalar-active-environment: staging

x-codeSamples

We provide examples for a lot of popular HTTP clients and frameworks. For something completely custom, for example to show the use of your own SDK, you can use x-codeSamples:

openapi: 3.1.0
info:
  title: Val Town API
  version: 1.0
paths:
  '/v1/eval':
    post:
+      x-codeSamples:
+      - label: ValTown JS SDK
+        lang: JavaScript
+        source: |-
+          import ValTown from '@valtown/sdk';
+
+          const valTown = new ValTown();
+
+          async function main() {
+            const valRunAnonymousResponse = await valTown.vals.runAnonymous({ code: 'console.log(1);' });
+
+            console.log(valRunAnonymousResponse);
+          }
+
+          main();

x-displayName

You can overwrite tag names with x-displayName.

openapi: 3.1.0
info:
  title: Example
  version: 1.0
tags:
  - name: pl4n3t5
+    x-displayName: planets
paths:
  '/planets':
    get:
      summary: Get all planets
      tags:
        - pl4n3t5

x-tagGroups

You can group your tags with x-tagGroups.

openapi: 3.1.0
info:
  title: Example
  version: 1.0
tags:
  - name: planets
+x-tagGroups:
+  - name: galaxy
+    tags:
+      - planets
paths:
  '/planets':
    get:
      summary: Get all planets
      tags:
        - planets

x-scalar-ignore

You can hide operations and webhooks from the reference with x-scalar-ignore.

openapi: 3.1.0
info:
  title: Example
  version: 1.0
paths:
  '/planets':
    get:
      summary: Get all planets
    post:
      summary: Create a new planet
+      x-scalar-ignore: true

Or to hide a tag and the operations under it:

openapi: 3.1.0
info:
  title: Example
  version: 1.0
tags:
  - name: planets
+    x-scalar-ignore: true
paths:
  '/planets':
    get:
      summary: Get all planets
      tags:
        - planets
    post:
      summary: Create a new planet
      tags:
        - planets

Aliases: x-internal

x-additionalPropertiesName

OpenAPI allows description of "additionalProperties" that may be included in a schema. Their names are unknown, but the field types can be added to the API description so that producers and consumers understand whether additional fields are permitted and any additional rules that apply.

Since the field names are not specified, they are displayed with a generic name in the API reference documentation. Use x-additionalPropertiesName to display a more meaningful name in this scenario.

The following example shows a schema that accepts any fields as long as the values are numbers between 0-100, for a set of sensors reporting fill levels:

components:
  schemas:
    FillLevel:
      type: object
      properties:
        reportTime:
          type: string
          format: date-time
          description: Report creation time.
      required:
        - reportTime
      additionalProperties:
        x-additionalPropertiesName: percentage
        type: integer
        minimum: 0
        maximum: 100

The additional properties appear in the documentation as percentage*.

x-scalar-stability

You can show the stability of an endpoint by settings the x-scalar-stability to either stable, experimental or deprecated. The native deprecated property will take precedence.

openapi: 3.1.0
info:
  title: Example
  version: 1.0
paths:
  '/planets':
    get:
      summary: Get all planets
    post:
      summary: Create a new planet
+      x-scalar-stability: 'experimental'

x-enum-descriptions

You can add a descriptions to enum values with x-enum-descriptions:

openapi: 3.1.0
info:
  title: Example
  version: 1.0
components:
  schemas:
    CustomerCancellationReason:
      type: string
      enum:
      - missing_features
      - too_expensive
      - unused
      - other
+      x-enum-descriptions:
+        missing_features: Missing features
+        too_expensive: Too expensive
+        unused: Unused
+        other: Other

Aliases: x-enumDescriptions

x-enum-varnames

You can provide variable names for enum values with x-enum-varnames. These names will be displayed alongside the enum values in the format value = varname:

openapi: 3.1.0
info:
  title: Example
  version: 1.0
components:
  schemas:
    HttpStatusCode:
      type: integer
      enum:
      - 100
      - 200
      - 300
      - 400
      - 500
+      x-enum-varnames:
+      - Continue
+      - OK
+      - MultipleChoices
+      - BadRequest
+      - InternalServerError

This will display as: 100 = Continue, 200 = OK, 300 = MultipleChoices, etc.

Aliases: x-enumNames

x-scalar-sdk-installation

We generate custom code examples for all languages, but you might have a custom SDK for your API. Provide installation instructions in the header like shown in the example below.

You can use description (supports Markdown) or source (for shell scripts) or both.

openapi: 3.1.0
info:
  title: Example
  version: 1.0
+  x-scalar-sdk-installation:
+  - lang: Node
+    description: Install our **Custom SDK** for Node.js from npm:
+    source: |-
+      npm install @your-awesome-company/sdk