# 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](../develop/cache) 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:

```yaml title="artist.yaml"
urlPath: /artist/:id
request:
  - fieldName: id
    fieldIn: path
    description: constituent id
    validators:
      - required
// highlight-start
sample:
  parameters:
    id: '1'
  profile: duck
// highlight-end
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](./validator) 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:

```sql title="artists.sql"
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 > 18](./img/api-req-constraint.png)

## 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:

```yaml title="artist.yaml"
request:
  - fieldName: age
    fieldIn: query
    type: number
// highlight-next-line
    description: Filter the age of artists
    validators:
      - required
      - name: integer
        args:
          min: 18
response:
  - name: ArtistBio
// highlight-next-line
    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.
