CLI Options

The Serverpod Swagger package includes a command-line interface (CLI) tool for generating OpenAPI specifications from your Serverpod protocol definitions. This page documents the available options for the CLI tool.

Overview

The generate.dart script in the bin directory is used to generate OpenAPI specifications from your Serverpod protocol definitions. The tool analyzes your Dart code, extracts endpoint information, and generates a JSON file that conforms to the OpenAPI specification.

Basic Usage

To use the CLI tool, run the following command from your project root directory:

dart run serverpod_swagger:generate [options]

Available Options

Option	Description	Default
`--output`	Path to the output file where the generated OpenAPI specification will be saved.	`apispec.json`
`--title`	The title of the API that will be displayed in the Swagger UI.	Your project name (derived from pubspec.yaml)
`--description`	A description of the API that will be displayed in the Swagger UI.	Empty
`--version`	The version of the API that will be displayed in the Swagger UI.	`1.0.0`
`--server-url`	The URL of the server that will be used for the "Try it out" feature in Swagger UI.	`http://localhost:8080`
`--server-description`	A description of the server that will be displayed in the Swagger UI.	Development server
`--source-dir`	The directory containing the Serverpod protocol definitions to analyze.	`lib/src/protocol`
`--schema-dir`	The directory containing custom schema definitions in YAML format.	`lib/src/openapi`
`--help`	Display help information about the available options.	N/A

Example Commands

Basic Generation

Generate an OpenAPI specification with default options:

dart run serverpod_swagger:generate

Custom Output Path

Generate an OpenAPI specification and save it to a custom location:

dart run serverpod_swagger:generate --output=public/api/openapi.json

Custom API Information

Generate an OpenAPI specification with custom API information:

dart run serverpod_swagger:generate   --title="My Awesome API"   --description="A comprehensive API for my application"   --version="2.1.0"

Custom Server Information

Generate an OpenAPI specification with custom server information:

dart run serverpod_swagger:generate   --server-url="https://api.example.com"   --server-description="Production API Server"

Multiple Servers

To specify multiple servers, you can provide the server URL and description options multiple times:

dart run serverpod_swagger:generate   --server-url="https://api.example.com"   --server-description="Production API Server"   --server-url="https://staging-api.example.com"   --server-description="Staging API Server"   --server-url="http://localhost:8080"   --server-description="Development Server"

Integration with Build Process

You can integrate the OpenAPI generation into your build process by adding a script to your package.json file (if you're using npm) or creating a shell script that runs the generator.

Example Shell Script

#!/bin/bash

# Generate OpenAPI specification
dart run serverpod_swagger:generate   --title="My API"   --description="API for my application"   --version="1.0.0"   --output="public/api/openapi.json"

# Start the server
dart bin/main.dart

Documentation