swaggest/rest

The Request Decoder maps HTTP request data into Go structs using field tags. This allows you to define your input port (the data your business logic needs) and its validation constraints in a single place.

Supported parameter locations via tags:

• path: URI parameters (e.g., /users/{name})
• query: URL query parameters (e.g., ?locale=en-US)
• formData: Request body with application/x-www-form-urlencoded or multipart/form-data
• form: Acts as either formData or query
• json: Request body with application/json
• cookie: Request cookies
• header: HTTP request headers
• contentType: The content type of the raw request body

To disallow unknown parameters, use an unnamed field with tags like query:"_" or cookie:"_" and set additionalProperties:"false".

type helloInput struct {
    Locale string `query:"locale" default:"en-US" pattern:"^[a-z]{2}-[A-Z]{2}$" enum:"ru-RU,en-US"`
    Name   string `path:"name" minLength:"3"` 

    // Disallow unknown query and cookie parameters
    _ struct{} `query:"_" cookie:"_" additionalProperties:"false"`
}

For cookie-based security, you must implement a custom middleware to extract the cookie and inject it into the request context, then use nethttp.APIKeySecurityMiddleware to document the requirement in the OpenAPI schema.

// 1. Custom middleware to extract cookie and put it in context
sessMW := func(handler http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if c, err := r.Cookie("sessid"); err == nil {
            r = r.WithContext(context.WithValue(r.Context(), "sessionID", c.Value))
        }
        handler.ServeHTTP(w, r)
    })
}

// 2. Middleware to document the cookie security in OpenAPI
sessDoc := nethttp.APIKeySecurityMiddleware(s.OpenAPICollector, "User",
    "sessid", oapi.InCookie, "Session cookie.")

// 3. Apply to routes
s.Route("/deeper-with-session", func(r chi.Router) {
    r.Group(func(r chi.Router) {
        r.Use(sessMW, sessDoc)
        r.Method(http.MethodGet, "/one", nethttp.NewHandler(dummy()))
    })
})

The REST router is a wrapper around github.com/go-chi/chi. To function correctly, you must configure specific middlewares for OpenAPI documentation, request decoding, and response encoding.

Required Middlewares

• nethttp.OpenAPIMiddleware(apiSchema)
• request.DecoderMiddleware(decoderFactory)
• response.EncoderMiddleware

Recommended/Optional Middlewares

• request.ValidatorMiddleware(validatorFactory): Performs request validation (recommended).
• response.ValidatorMiddleware(validatorFactory)
• gzip.Middleware: Enables response compression.

Setup Example

To support path parameters (e.g., in Chi), you should configure the decoderFactory with chirouter.PathToURLValues.

// Setup request decoder and validator.
validatorFactory := jsonschema.NewFactory(apiSchema, apiSchema)
decoderFactory := request.NewDecoderFactory()
decoderFactory.SetDecoderFunc(rest.ParamInPath, chirouter.PathToURLValues)

// Create router.
r := chirouter.NewWrapper(chi.NewRouter())

// Setup middlewares.
r.Use(
    middleware.Recoverer,                          // Panic recovery.
    nethttp.OpenAPIMiddleware(apiSchema),          // Documentation collector.
    request.DecoderMiddleware(decoderFactory),     // Request decoder setup.
    request.ValidatorMiddleware(validatorFactory), // Request validator setup.
    response.EncoderMiddleware,                    // Response encoder setup.
    gzip.Middleware,                               // Response compression with support for direct gzip pass through.
)

To build a REST API, you follow a pattern of initializing a web service, defining input/output port types with struct tags, creating a use case interactor, and registering handlers.

Key steps:

1. Initialize Service: Use web.NewService with an OpenAPI reflector.
2. Define Ports: Use Go structs for inputs and outputs. Use struct tags like query, path, header, and json to define parameter locations and JSON schema constraints (e.g., minLength, pattern, enum).
3. Create Interactor: Use usecase.NewInteractor to define the business logic. The interactor function receives a context.Context, the input struct, and a pointer to the output struct.
4. Register Routes: Use methods like s.Get(path, interactor) to map routes to use cases.
5. Documentation: Use s.Docs(path, swgui.New) to serve Swagger UI.

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"net/http"
	"time"

	"github.com/swaggest/openapi-go/openapi31"
	"github.com/swaggest/rest/response/gzip"
	"github.com/swaggest/rest/web"
	swgui "github.com/swaggest/swgui/v5emb"
	"github.com/swaggest/usecase"
	"github.com/swaggest/usecase/status"
)

func main() {
	s := web.NewService(openapi31.NewReflector())

	s.OpenAPISchema().SetTitle("Basic Example")
	s.OpenAPISchema().SetDescription("This app showcases a trivial REST API.")
	s.OpenAPISchema().SetVersion("v1.2.3")

	s.Wrap(gzip.Middleware)

	type helloInput struct {
		Locale string `query:"locale" default:"en-US" pattern:"^[a-z]{2}-[A-Z]{2}$" enum:"ru-RU,en-US"`
		Name   string `path:"name" minLength:"3"` 
		_ struct{} `query:"_" cookie:"_" additionalProperties:"false"`
	}

	type helloOutput struct {
		Now     time.Time `header:"X-Now" json:"-"`
		Message string    `json:"message"`
	}

	u := usecase.NewInteractor(func(ctx context.Context, input helloInput, output *helloOutput) error {
		output.Message = fmt.Sprintf("Hello, %s!", input.Name)
		output.Now = time.Now()
		return nil
	})

	s.Get("/hello/{name}", u)
	s.Docs("/docs", swgui.New)

	if err := http.ListenAndServe("localhost:8011", s); err != nil {
		log.Fatal(err)
	}
}