Skip to content
/ goa Public

Design-first Go framework that generates API code, documentation, and clients. Define once in an elegant DSL, deploy as HTTP and gRPC services with zero drift between code and docs.

License

Notifications You must be signed in to change notification settings

goadesign/goa

Repository files navigation

Goa

Release Go Doc GitHub Action: Test Go Report Card Software License Gurubase
Slack: Goa Slack: Sign-up BSky: Goa

Wizard Logo

Goa Design Wizard

Use the Goa Design Wizard to:

  • Create Goa designs in seconds
  • Review existing designs
  • Explore the Goa DSL

(requires a ChatGPT Plus subscription)

Goa - Design First, Code With Confidence

Overview

Goa transforms how you build APIs and microservices in Go with its powerful design-first approach. Instead of writing boilerplate code, you express your API's intent through a clear, expressive DSL. Goa then automatically generates production-ready code, comprehensive documentation, and client librariesβ€”all perfectly aligned with your design.

The result? Dramatically reduced development time, consistent APIs, and the elimination of the documentation-code drift that plagues traditional development.

Why Goa?

Traditional API development suffers from:

  • Inconsistency: Manually maintained docs that quickly fall out of sync with code
  • Wasted effort: Writing repetitive boilerplate and transport-layer code
  • Painful integrations: Client packages that need constant updates
  • Design afterthoughts: Documentation added after implementation, missing key details

Goa solves these problems by:

  • Generating 30-50% of your codebase directly from your design
  • Ensuring perfect alignment between design, code, and documentation
  • Supporting multiple transports (HTTP and gRPC) from a single design
  • Maintaining a clean separation between business logic and transport details

🌟 Key Features

  • Expressive Design Language: Define your API with a clear, type-safe DSL that captures your intent
  • Comprehensive Code Generation:
    • Type-safe server interfaces that enforce your design
    • Client packages with full error handling
    • Transport layer adapters (HTTP/gRPC) with routing and encoding
    • OpenAPI/Swagger documentation that's always in sync
    • CLI tools for testing your services
  • Multi-Protocol Support: Generate HTTP REST and gRPC endpoints from a single design
  • Clean Architecture: Business logic remains separate from transport concerns
  • Enterprise Ready: Supports authentication, authorization, CORS, logging, and more

πŸ”„ How It Works

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Design API  │────>β”‚ Generate Code│────>β”‚ Implement Business  β”‚
β”‚ using DSL   β”‚     β”‚ & Docs       β”‚     β”‚ Logic               β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  1. Design: Express your API's intent in Goa's DSL
  2. Generate: Run goa gen to create server interfaces, client code, and documentation
  3. Implement: Focus solely on writing your business logic in the generated interfaces
  4. Evolve: Update your design and regenerate code as your API evolves

πŸš€ Quick Start

# Install Goa
go install goa.design/goa/v3/cmd/goa@latest

# Create a new module
mkdir hello && cd hello
go mod init hello

# Define a service in design/design.go
mkdir design
cat > design/design.go << EOF
package design

import . "goa.design/goa/v3/dsl"

var _ = Service("hello", func() {
    Method("say_hello", func() {
        Payload(func() {
            Field(1, "name", String)
            Required("name")
        })
        Result(String)

        HTTP(func() {
            GET("/hello/{name}")
        })
    })
})
EOF

# Generate the code
goa gen hello/design
goa example hello/design

# Build and run
go mod tidy
go run cmd/hello/*.go --http-port 8000

# In another terminal
curl http://localhost:8000/hello/world

The example above:

  1. Defines a simple "hello" service with one method
  2. Generates server and client code
  3. Starts a server that logs requests server-side (without displaying any client output)

πŸ“š Documentation

Our completely redesigned documentation site at goa.design provides comprehensive guides and references:

πŸ› οΈ Real-World Examples

The examples repository contains complete, working examples demonstrating:

  • Basic: Simple service showcasing core Goa concepts
  • Cellar: A more complete REST API example
  • Cookies: HTTP cookie management
  • Encodings: Working with different content types
  • Error: Comprehensive error handling strategies
  • Files & Upload/Download: File handling capabilities
  • HTTP Status: Custom status code handling
  • Interceptors: Request/response processing middleware
  • Multipart: Handling multipart form submissions
  • Security: Authentication and authorization examples
  • Streaming: Implementing streaming endpoints
  • Tracing: Integrating with observability tools
  • TUS: Resumable file uploads implementation

🏒 Success Stories

"Goa reduced our API development time by 40% while ensuring perfect consistency between our documentation and implementation. It's been a game-changer for our microservices architecture." - Lead Engineer at FinTech Company

"We migrated 30+ services to Goa and eliminated documentation drift entirely. Our teams can now focus on business logic instead of maintaining OpenAPI specs by hand." - CTO at SaaS Platform

🀝 Community & Support

πŸ“£ What's New

Jan 2024: Goa's powerful design DSL is now accessible through the Goa Design Wizard, a specialized AI trained on Goa. Generate service designs through natural language conversations!

February 2025: The Goa website has been completely redesigned with extensive new documentation, tutorials, and guides to help you build better services.

πŸ“„ License

MIT License - see LICENSE for details.

About

Design-first Go framework that generates API code, documentation, and clients. Define once in an elegant DSL, deploy as HTTP and gRPC services with zero drift between code and docs.

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks