gofasta swagger

Generates OpenAPI/Swagger documentation from annotation comments in your Go source code. The generated specification is served as an interactive Swagger UI at /swagger/index.html when the server is running.

This command uses swag under the hood to parse Go annotations and produce the OpenAPI spec.

Usage


gofasta swagger

Run this command from the root directory of your Gofasta project.

This command takes no flags.

Examples

Generate Swagger docs:


gofasta swagger

How It Works

The gofasta swagger command runs:


go tool swag init -g app/main/main.go -o docs/

This parses the Go annotation comments in your source code starting from app/main/main.go and generates the OpenAPI specification files in the docs/ directory.

Annotation Format

Gofasta controllers use swag-style annotations to describe API endpoints. Here is an example from a generated controller:


// CreateProduct godoc
// @Summary      Create a new product
// @Description  Create a new product with the provided data
// @Tags         Products
// @Accept       json
// @Produce      json
// @Param        body  body      dtos.CreateProductRequest  true  "Product data"
// @Success      201   {object}  dtos.ProductResponse
// @Failure      400   {object}  dtos.ErrorResponse
// @Failure      401   {object}  dtos.ErrorResponse
// @Failure      500   {object}  dtos.ErrorResponse
// @Security     BearerAuth
// @Router       /api/v1/products [post]
func (c *ProductController) Create(ctx *gin.Context) {
    // ...
}

The general API information is defined in app/main/main.go:


// @title        My App API
// @version      1.0
// @description  REST API for My App
// @host         localhost:8080
// @BasePath     /api/v1
// @securityDefinitions.apikey BearerAuth
// @in header
// @name Authorization

What It Generates

Running gofasta swagger produces three files:

File	Description
`docs/docs.go`	Go file that embeds the spec for serving at runtime
`docs/swagger.json`	OpenAPI spec in JSON format
`docs/swagger.yaml`	OpenAPI spec in YAML format

Accessing Swagger UI

After generating the docs and starting the server, the interactive Swagger UI is available at:


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

This provides an interactive interface where you can browse all endpoints, view request/response schemas, and test API calls directly from the browser.

When to Run

Run gofasta swagger after:

Adding or modifying controller annotations
Changing DTO structures that are referenced in annotations
Adding new routes or controllers
Updating the general API information in app/main/main.go

gofasta serve — start the server to view Swagger UI
gofasta dev — start the dev server to view Swagger UI