Type Referencing

Overview

Type parameters in curly braces {type} are used throughout Autoswag to reference schemas. They appear in:

• @accept - Request body schema
• @response - Response body schema
• @pathParam - Path parameter type
• @queryParam - Query parameter type
• @headerParam - Header parameter type
• @cookieParam - Cookie parameter type

Syntax

@<tag> {<type>} [other parameters...]

The {type} parameter can represent:

1. Primitive types - string, number, boolean, null
2. TypeScript type references - Interface or type alias names
3. TypeScript type expressions - Inline type definitions
4. OpenAPI component references - Pre-defined schemas with ref: prefix
5. Format constants - Built-in formats like uuid, email, date-time

1. Primitive Types

The simplest case - reference a basic JavaScript type directly.

Example

/**
 * ...
 * @response {number} 200
 * ...
 */

Generated OpenAPI:

{
    "type": "number"
}

Edge case: Null type

/**
 * ...
 * @response {null} 200
 * ...
 */

Generates { "type": "null" } in OpenAPI 3.1 or { "nullable": true } in OpenAPI 3.0.

2. TypeScript Type References

Reference any TypeScript type defined in your codebase. This is the primary feature of Autoswag.

Example

interface User {
    id: string
    name: string
    email?: string
}

/**
 * ...
 * @response {User} 200 User found
 * ...
 */

Generated OpenAPI:

{
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid"
        },
        "name": {
            "type": "string"
        },
        "email": {
            "type": "string"
        }
    },
    "required": ["id", "name"]
}

Support

Autoswag supports almost every TypeScript type, even @typedef. More on how types are resolved here

Imported Type References

Types can be imported from other files:

types/user.ts

export interface User {
    id: string
    name: string
    email?: string
}

api/users.ts

import type { User } from '../types/user'

/**
 * ...
 * @response {User[]} 200 User list
 * ...
 */

Cross-File Resolution

Autoswag uses the TypeScript compiler API to resolve all imports automatically. It respects your tsconfig.json path aliases.

3. TypeScript Type Expressions

Use TypeScript syntax directly in the type parameter for inline types.

WARNING

To implement such functionality, Autoswag is forced to create temporary source files. We do not recommend using type expressions for large projects and files.

Example

/**
 * ...
 * @response {'success'|'error'} 200 Status
 * ...
 */

Generated OpenAPI:

{
    "type": "string",
    "enum": ["success", "error"]
}

4. OpenAPI Component References

Reference pre-defined schemas in baseDoc.components.schemas using the ref: prefix.

Defining Components in baseDoc

import { generate, OpenApiVersion } from 'autoswag'

const spec = generate({
    source: ['src/api/**/*.ts'],
    baseDoc: {
        // ...
        components: {
            schemas: {
                Error: {
                    type: 'object',
                    properties: {
                        code: { type: 'string' },
                        message: { type: 'string' },
                    },
                    required: ['code', 'message'],
                },
            },
        },
        // ...
    },
})

Using Component References

/**
 * ...
 * @response {ref:Error} 500 Server error
 * ...
 */

Generated OpenAPI:

{
    "$ref": "#/components/schemas/Error"
}

When to Use Component References

Use ref: when:

• Sharing hand-written schemas across many endpoints
• Integrating with existing OpenAPI documents
• Using non-json schemas

Use TypeScript types when:

• Type is defined in your codebase
• You want type safety and IDE autocomplete
• Schema matches your actual data structures

5. Format Constants

Use built-in format strings directly for common patterns.

UUID

/**
 * ...
 * @pathParam {uuid} User ID
 * ...
 */

Generated OpenAPI:

{
    "type": "string",
    "format": "uuid"
}

Email

/**
 * ...
 * @queryParam {email} email Email address
 * ...
 */

Generated OpenAPI:

{
    "type": "string",
    "format": "email"
}

All Supported Format Constants

Click to see all 76+ supported format constants

Name	Associated Type
base64url	string
binary	string
byte	string
char	string
commonmark	string
date-time-local	string
date-time	string
date	string
decimal	number
decimal128	number
double-int	number
double	number
duration	string
email	string
float	number
hostname	string
html	string
http-date	string
idn-email	string
idn-hostname	string
int16	number
int32	number
int64	number
int8	number
ipv4-cidr	string
ipv4	string
ipv6-cidr	string
ipv6	string
iri-reference	string
iri	string
json-pointer	string
language	string
media-range	string
password	string
regex	string
relative-json-pointer	string
sf-binary	string
sf-boolean	string
sf-decimal	string
sf-integer	number
sf-string	string
sf-token	string
time-local	string
time	string
uint16	number
uint32	number
uint64	number
uint8	number
unixtime	number
uri-reference	string
uri-template	string
uri	string
uuid	string

Type Resolution Order

When Autoswag encounters a type parameter, it resolves it in this order:

1. Check if primitive - string, number, boolean, null
2. Check if format constant - uuid, email, date-time, etc.
3. Check if component reference - Starts with ref:
4. Parse as TypeScript expression - Use TypeScript compiler API
5. If type could not be resolved, then using {}