Skip to main content

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


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:

urlPath: /artist/:id
- fieldName: id
fieldIn: path
description: constituent id
- required
id: '1'
profile: duck
- duck

The sample field has two properties:

Property nameRequiredDescription
parametersNThe parameters we should use to send sampling queries.
profileYThe 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:

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

will generate the following documentation:

api request with constraint age &gt; 18

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:

- fieldName: age
fieldIn: query
type: number
description: Filter the age of artists
- required
- name: integer
min: 18
- 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.