A spec first approach to building AdonisJS applications using OpenAPI.

Unlike other OpenAPI packages for AdonisJS, this package is designed to be used with a spec first approach. This means that you define your API using OpenAPI and then generate the routes for your application.

npm i openapi-adonisjs

Create a new OpenAPI spec file in the resources/openapi folder of your project. For example, resources/openapi/specs.yaml.

Run node ace openapi:codegen to generate the routes for your application.

This will generate the routes in the generated/openapi-server folder of your project. Add these to the aliases in tsconfig.json and package.json.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "#generated": [
        "generated/*"
      ]
    }
  }
}

The operations with tags will generate an interface and a factory function. You should implement these interfaces in your controllers and register the routes in your start/routes.ts file using the factory function.

The operations without tags will generate a factory function only. These functions accept a handler which you need to implement.

The second argument to the class methods and handler functions will be a an object with validated request body and parameters. You should return a serializable object of the corresponding response type.

// app/controllers/pets_controller.ts
import type {PetsContract} from '#generated/openapi-server'

export default class PetsController implements PetsContract {
  async create(ctx, {body, params}) {
    // Implement the create method
  }
}

// start/routes.ts
import router from '@adonisjs/core/services/router'
import PetsController from '#app/controllers/pets_controller'

router.openapi(petsControllerFactory(PetsController))
router.openapi(createPetFactory((ctx, {body, params}) => {
  // Implement the createPet handler
}))

// Serve the OpenAPI spec
router.openapiDocs('/specs.yaml')

// Swagger UI, requires `router.openapiDocs` to be called first
router.openapiUi('/docs')

Please take a look at the example folder for a complete example implementing the petstore API.

You can configure the package by updating the config/openapi.ts file in your project.

• Add support for OpenAPI security
• Add a command to check if all the routes are implemented