This directory contains the auto-generated OpenAPI/Swagger documentation for the Voiceflow CLI API server.

• docs.go - Generated Go code with embedded OpenAPI specification
• swagger.json - OpenAPI 2.0 specification in JSON format
• swagger.yaml - OpenAPI 2.0 specification in YAML format
• docs.go.backup - Backup of the previous manual docs.go file (for reference)

The documentation is automatically generated from the Go code annotations using swaggo/swag.

# Generate docs using Make
make docs

# Or generate docs directly
./scripts/generate-docs.sh

# Or use swag directly
swag init --generalInfo server/server.go --output server/docs

# Auto-regenerate docs when code changes (requires fswatch)
make watch-docs

Start the API server and visit the Swagger UI:

# Start development server with Swagger UI
make dev

# Or start server directly
go run . server --debug

Then visit: http://localhost:8080/swagger/index.html

You can also serve the static files directly:

# Serve documentation files locally
make serve-docs

Then visit:

• JSON: http://localhost:8000/swagger.json
• YAML: http://localhost:8000/swagger.yaml

The documentation is generated from Go annotations in the source code:

Located in server/server.go:

// @title Voiceflow CLI API
// @version 1.0
// @description API server for Voiceflow CLI test execution and management
// @host localhost:8080
// @BasePath /

Located in server/handlers/handlers.go:

// @Summary Execute a test suite
// @Description Execute a Voiceflow test suite and return execution ID
// @Tags tests
// @Accept json
// @Produce json
// @Param request body TestExecutionRequest true "Test execution request"
// @Success 202 {object} TestExecutionResponse
// @Failure 400 {object} ErrorResponse
// @Router /api/v1/tests/execute [post]

The API now supports specifying a custom Voiceflow subdomain for individual test executions:

{
  "api_key": "VF.DM.YOUR_API_KEY",
  "voiceflow_subdomain": "staging-env",
  "suite": {
    "name": "Multi-Environment Test",
    "description": "Test that runs against custom subdomain",
    "environment_name": "production",
    "tests": [
      {
        "id": "custom_subdomain_test",
        "test": {
          "name": "Basic conversation test",
          "description": "Test basic conversation flow",
          "interactions": [
            {
              "id": "launch_interaction",
              "user": {
                "type": "launch"
              },
              "agent": {
                "validate": [
                  {
                    "id": "welcome_validation",
                    "type": "contains",
                    "value": "welcome"
                  }
                ]
              }
            },
            {
              "id": "text_interaction",
              "user": {
                "type": "text",
                "text": "hello"
              },
              "agent": {
                "validate": [
                  {
                    "id": "response_validation",
                    "type": "contains",
                    "value": "hi"
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}

Edit the annotations in server/server.go to change:

• API title and description
• Contact information
• License information
• Host and base path

1. Add handler function with proper annotations in server/handlers/handlers.go
2. Register the route in server/server.go
3. Run make docs to regenerate documentation

Update the struct definitions in server/handlers/handlers.go and add appropriate JSON tags:

type MyResponse struct {
    Field1 string `json:"field1" example:"example value"`
    Field2 int    `json:"field2" example:"42"`
}

The generated documentation is automatically integrated into the server:

1. Import: The docs package is imported in server/server.go
2. Registration: Swagger info is registered via init() function
3. Serving: Swagger UI is served at /swagger/* when enabled

# Install required tools
make install-tools

# Generate documentation
make docs

# Validate generated OpenAPI spec
make validate-docs

# Start development server with docs
make dev

# Build and run
make build && ./voiceflow-cli server

• Swagger/OpenAPI Specification
• swaggo/swag Documentation
• Gin-Swagger Integration
• OpenAPI Examples

Note: This documentation is auto-generated. Do not edit docs.go, swagger.json, or swagger.yaml manually. Instead, modify the source code annotations and regenerate using make docs.