dox_openapi

Make an OpenAPI 3.1 document (JSON and YAML) and serve it with a Scalar or Swagger UI docs page.

Part of Dox, a web backend framework for Dart, like Laravel. Source code: github.com/dartondox/dox-openapi.

Install

In a Dox app you do not add it and you write no docs code. dox_builder reads your routes, DTOs and controllers, and dox_core serves /docs. To use it on its own:

dart pub add dox_openapi

To see what is ready and what may still change, read Status and roadmap.

Use it

Describe routes by hand with ApiDoc:

import 'package:dox_openapi/dox_openapi.dart';

void main() async {
  ApiDoc docs = ApiDoc();
  docs.route('GET', '/users/{id}',
      summary: 'Get one user',
      tags: <String>['users'],
      params: <String, Object>{'id': <String, dynamic>{'type': 'integer'}},
      responses: <int, ResponseDoc>{
        404: const ResponseDoc(description: 'Not found'),
      },
      // Text keys like `default` or `2XX` go here.
      namedResponses: <String, ResponseDoc>{
        'default': const ResponseDoc(description: 'Any other error'),
      });

  OpenApi api = OpenApi(info: const Info(title: 'My API', version: '1.0.0'), docs: docs);

  print(api.toYaml());
  await api.writeFiles('storage/openapi'); // openapi.json + openapi.yaml

  OpenApiServer server = OpenApiServer(api);
  OpenApiResponse? page = server.handle('/docs'); // page.body, page.contentType
}

Features

• OpenAPI 3.1 output as a Map, JSON text or YAML.
• OpenApiServer answers /docs, /openapi.json and /openapi.yaml. It does not need a router.
• Scalar docs page by default. DocsUi.swagger gives Swagger UI.
• A schema can be a JSON Schema Map, a dox_validation schema, or any object with toJsonSchema().
• DoxRouteAdapter adds a basic entry for each route you did not describe. On a GET or DELETE route, a body schema with properties becomes query params.
• Paths with {id} or :id both become {id}.
• An optional param {id?} gives two paths, /users/{id} and /users, because OpenAPI path params are always required. This also works for an optional param in the middle: /a/{x?}/b gives /a/{x}/b and /a/b.

Documentation

• OpenAPI
• API reference

License

MIT. See LICENSE.