API Documentation

In this section, we will discuss how VulcanSQL automatically generates API documentation in the Swagger format. This feature enables developers to easily understand and interact with the API endpoints, making it a valuable tool for collaboration and testing.

VulcanSQL automatically generates and serves the API documentation for you. To view the documentation, navigate to <vulcan-endpoint>/doc after starting the VulcanSQL server. From this page, you can also download the API specification in the Swagger format.

Setting Sampler

caution

If caching is enabled in the API endpoint, the sampling funcaionality is disabled.

VulcanSQL offers a powerful feature called sampler that allows us to infer the response format by sending a sample query to your data warehouse. To enable this feature, you can set the sample property in each configuration file. For example:

artist.yaml

urlPath: /artist/:id
request:
  - fieldName: id
    fieldIn: path
    description: constituent id
    validators:
      - required
sample:
  parameters:
    id: '1'
  profile: duck
profiles:
  - duck

The sample field has two properties:

Property name	Required	Description
parameters	N	The parameters we should use to send sampling queries.
profile	Y	The profile name we should use to send sampling queries.

How Validation Enhances Documentation Generation

To ensure the stability of your API, you can add more validations and configure the appropriate arguments.

With the validations defined, VulcanSQL will automatically generate the validation part of documentation for you. For example, the following configuration file:

artists.sql

SELECT * FROM "artists"
WHERE age = {{ context.params.age | is_required | is_integer(min=18, max=100) }}

will generate the following documentation:

Adding Descriptions for Requests and Responses

To provide more clarity and context for your API, you can add descriptions for both the requests and the responses. This helps users understand the purpose and behavior of each field. For example:

artist.yaml

request:
  - fieldName: age
    fieldIn: query
    type: number
    description: Filter the age of artists
    validators:
      - required
      - name: integer
        args:
          min: 18
response:
  - name: ArtistBio
    description: The URL to the artist's bio
    required: true

In this case, we have added a description for the age request parameter and the ArtistBio response property.

Please note that you can also list response properties partially, and we will merge the result from the sampler to provide a more comprehensive API documentation.

By following these practices and adding more detailed information, you can create a comprehensive and informative API documentation for your VulcanSQL-based APIs.