Spot OpenAPI Specification

Spot OpenAPI Specification is a static site built using OpenAPI definitions and powered by ReDoc.

Table of Contents

• Requirements
• Local Development
• Build Artifacts
• Getting Help
• Community
• Contributing
• License
• Adding a New Documentation Section

Requirements

• Nvm
• Node.js
• Yarn

Local Development

• Start the ReDoc webserver (available at http://localhost:8080):

# using yarn
$ yarn serve

# using docker
$ make serve

• Validate the API definition against the OpenAPI schema:

# using yarn
$ yarn validate

# using docker
$ make validate

Build Artifacts

• Make a static HTML file with ReDoc:

# using yarn
$ yarn bundle:redoc

# using docker
$ make bundle-redoc

• Make a single JSON bundle of the OpenAPI spec:

# using yarn
$ yarn bundle:swagger

# using docker
$ make bundle-swagger

Getting Help

We use GitHub issues for tracking bugs and feature requests. Please use these community resources for getting help:

• Ask a question on Stack Overflow and tag it with spot-openapi.
• Join our Spot community on Slack.
• Open an issue.

Community

• Slack
• Twitter

Contributing

Please see the contribution guidelines.

License

Code is licensed under the Apache License 2.0.

Adding a New Documentation Section

The documentation is automatically split into sections based on x-tagGroups in api/spot.yaml.

Step 1: Add Tags

First, ensure your API endpoints have tags defined in their path files under api/services/:

# Example: api/services/myservice/paths/endpoint.yaml
get:
  tags:
    - My New Service
  summary: Get something
  # ...

Step 2: Add Tag Definition

Add the tag definition in api/spot.yaml under tags::

tags:
  # ...existing tags...
  - name: My New Service
    description: Description of my new service
    externalDocs:
      description: My Service Documentation
      url: https://docs.flexera.com/spot/myservice/

Step 3: Add Tag Group with Folders

Add a new group in api/spot.yaml under x-tagGroups: with x-folders to specify which service folders to include:

x-tagGroups:
  # ...existing groups...
  - name: My New Section
    x-folders:
      - myservice/
    tags:
      - My New Service
      - Another Related Tag

The x-folders array specifies which folders under api/services/ contain the paths for this section.

Step 4: Build and Test

yarn serve

Your new section will appear in the left menu automatically.

Structure Summary

File	Purpose
api/spot.yaml	Main spec with tags, x-tagGroups, and x-folders
api/services/*/	Service-specific paths, schemas, responses
scripts/build-sections.js	Generates split YAMLs per section (reads from x-tagGroups)
scripts/build-landing.js	Generates landing page with menu

Response Schema Patterns

Using Response Wrappers

Spot API uses standardized response wrappers to maintain consistency across all endpoints. When creating response schemas, follow these patterns:

Common Response Wrappers

• responseWrapper.yaml - Base wrapper with request and response.status properties
• responseItemWrapper.yaml - Extends base wrapper, adds count and kind properties
• paginatedResponseItemWrapper.yaml - Extends item wrapper, adds paginationInfo

⚠️ IMPORTANT: You MUST Define items Array

The common response wrappers (responseItemWrapper.yaml and paginatedResponseItemWrapper.yaml) do not include the response.items array. This is intentional to allow each endpoint to define its specific item type.

❌ Incorrect Usage (Missing items):

# api/services/myservice/responses/myResponse.yaml
description: My Response
content:
  application/json:
    schema:
      $ref: "../../../commons/schemas/responseItemWrapper.yaml"

✅ Correct Usage (Explicit items Definition):

# api/services/myservice/responses/myResponse.yaml
description: My Response
content:
  application/json:
    schema:
      allOf:
        - $ref: "../../../commons/schemas/responseItemWrapper.yaml"
        - type: object
          properties:
            response:
              type: object
              properties:
                items:
                  type: array
                  items:
                    $ref: "../schemas/myItemSchema.yaml"
                kind:
                  example: spotinst:myservice:item

Why This Pattern?

1. Type Safety: Each endpoint explicitly defines its item schema, enabling better code generation
2. Flexibility: Different endpoints can return different item types without conflicts
3. Validation: OpenAPI tools can validate the specific schema for each endpoint
4. Documentation: Generated docs show the exact response structure for each endpoint

Checklist for New Responses

When creating a new response that returns a list of items:

• Use allOf to extend responseItemWrapper.yaml or paginatedResponseItemWrapper.yaml
• Define response.items as an array with a specific item schema reference
• Define response.kind with an example value following the pattern: spotinst:service:itemType
• If paginated, ensure you're using paginatedResponseItemWrapper.yaml

Example: Complete Response File

# api/services/elastigroup/aws/responses/groups.yaml
description: Elastigroup Response
content:
  application/json:
    schema:
      allOf:
        - $ref: "../../../../commons/schemas/responseItemWrapper.yaml"
        - type: object
          properties:
            response:
              type: object
              properties:
                items:
                  type: array
                  items:
                    $ref: "../schemas/elastigroup.yaml"
                kind:
                  example: spotinst:aws:ec2:group