Types and parameters

Classes as schemas

One of the most powerful feature of this library is the ability to use classes as schemas. When using the @ApiProperty decorator it will automatically add the property to the generated schema and try to infer the type from your Typescript type.

app/schemas/post.ts

import {  } from '@foadonis/openapi/decorators'

export class  {
  @()
  declare : number

  @()
  declare : string
}

Advanced properties options

The @ApiProperty decorator also accepts the same properties as the original OpenAPI Schema object, allowing you to extend the generated schema.

app/schemas/post.ts

import {  } from '@foadonis/openapi/decorators'

export class  {
  @({
    : 17,
  })
  declare : number

  @({
    : 6,
    : 255,
    : 'How to create REST APIs with Adonis',
  })
  declare : string
}

Optional properties

Due to the lack of informations provided by the Typescript metadata it is not possible to infer if a property is optional. For this you can either use the required option or the @ApiOptionalProperty decorator.

app/schemas/post.ts

import { ,  } from '@foadonis/openapi/decorators'

export class  {
  @()
  declare : number

  @()
  declare : string

  @({ :  })
  declare ?: string

  @({ : , : false })
  declare ?: string
}

Explicit type

Sometimes the type of your property is too complex to be automatically inferred or might be serialized in a specific way. When it is the case, you should see a warning in the console. To resolve this, you simply have to define explicitly the type using the type option.

app/schemas/post.ts

import {  } from '@foadonis/openapi/decorators'

export class  {
  @({ : CustomSchema })
  : any
}

You can create custom type loaders to automatically generate schemas for inferred custom types, more information on the openapi-metadata documentation.

Circular dependencies

You may have circular dependencies in your schema, for example a Post can have a Post as a parent. In this situation, you must explicitly define the type using a Thunk:

app/schemas/post.ts

import {  } from '@foadonis/openapi/decorators'

export class  {
  @({ : () =>  })
  declare : 
}

Primitives

Primitives can be defined by using their name as a string or its constructor.

import { , ,  } from '@foadonis/openapi/decorators'

@({ : 'string' })
@({ :  })
@({ :  })

Arrays

You can configure a type to be an array by simply wrapping your base type in an array.

import { ,  } from '@foadonis/openapi/decorators'

@({ : [Post] })
@({ : [User] })

Raw schema

Sometimes you may want to define a raw OpenAPI schema. For this you can use the schema option.

import {  } from '@foadonis/openapi/decorators'
import {  } from '@foadonis/openapi'

@({
  : {
    : 'object',
    : {
      : {
        : (User)
      }
    }
  }
})

Enums

An enum type can be defined by providing an array of the available items or a Typescript enum.

import {  } from '@foadonis/openapi/decorators'

@({ : "api", : ["openapi", "graphql"] })

import {  } from '@foadonis/openapi/decorators'

enum  {
   = "graphql",
   = "openapi"
}

@({ : "api", :  })

On this page