spec

package module
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 31, 2025 License: MIT Imports: 16 Imported by: 19

README

oaswrap/spec

CI codecov Go Reference Go Report Card License

oaswrap/spec is a lightweight, framework-agnostic OpenAPI 3.x specification builder for Go.
It provides the core logic to describe your API operations, paths, parameters, and schemas — without locking you into any specific web framework.

This makes it easy to use with any router — directly or through adapters for frameworks like Fiber, Gin, Echo, and more.

Under the hood, oaswrap/spec uses swaggest/openapi-go for robust OpenAPI schema generation.

✅ Looking for a ready-to-use Fiber integration? Check out oaswrap/fiberopenapi.

✨ Features

  • ✅ Programmatically build OpenAPI 3.x specs in pure Go.
  • ✅ Powered by swaggest/openapi-go.
  • ✅ No runtime web server logic — focused purely on schema generation.
  • ✅ Designed to be wrapped by adapters for popular frameworks.
  • ✅ Supports struct tags for request/response models.
  • ✅ Write specs to JSON or YAML, validate before serving or publishing.

📦 Installation

go get github.com/oaswrap/spec

⚡️ Quick Example

package main

import (
	"log"

	"github.com/oaswrap/spec"
	"github.com/oaswrap/spec/option"
)

func main() {
	// Create a new OpenAPI router with basic info and security scheme
	r := spec.NewRouter(
		option.WithTitle("My API"),
		option.WithVersion("1.0.0"),
		option.WithDescription("Example API"),
		option.WithServer("https://api.example.com"),
		option.WithSecurity("bearerAuth", option.SecurityHTTPBearer("Bearer")),
	)

	// Versioned API group
	v1 := r.Group("/api/v1")

	// Auth routes
	v1.Route("/auth", func(r spec.Router) {
		r.Post("/login",
			option.Summary("User Login"),
			option.Request(new(LoginRequest)),
			option.Response(200, new(Response[Token])),
		)

		r.Get("/me",
			option.Summary("Get Profile"),
			option.Security("bearerAuth"),
			option.Response(200, new(Response[User])),
		)
	}, option.RouteTags("Authentication"))

	// Generate the OpenAPI file
	if err := r.WriteSchemaTo("openapi.yaml"); err != nil {
		log.Fatal(err)
	}

	log.Println("✅ OpenAPI schema generated at openapi.yaml")
}

// Example request & response structs

type LoginRequest struct {
	Username string `json:"username" required:"true"`
	Password string `json:"password" required:"true"`
}

type Token struct {
	AccessToken string `json:"access_token"`
}

type User struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

type Response[T any] struct {
	Status int `json:"status"`
	Data   T   `json:"data"`
}

✨ See it live: You can view the generated OpenAPI documentation for this example online at Rest.Wiki Viewer.

📚 Documentation

For detailed usage instructions, see the pkg.go.dev documentation.

📄 License

This project is licensed under the MIT License.

Made with ❤️ by oaswrap

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Generator 

type Generator struct {
	// contains filtered or unexported fields
}

Generator is a struct that implements the Router interface. It is used to generate OpenAPI specifications based on the defined routes and operations.

func NewGenerator 

func NewGenerator(opts ...option.OpenAPIOption) *Generator

NewGenerator creates a new Generator instance with the provided OpenAPI options.

It initializes the reflector and sets up the OpenAPI configuration.

func NewRouter added in v0.1.3 

func NewRouter(opts ...option.OpenAPIOption) *Generator

NewRouter creates a new Router instance with the provided OpenAPI options.

It initializes the reflector and sets up the OpenAPI configuration.

func (*Generator) Add added in v0.1.2 

func (g *Generator) Add(method, path string, opts ...option.OperationOption) Route

Add registers a new operation with the specified method and path. It applies the provided operation options to the operation context.

func (*Generator) Config added in v0.1.2 

func (g *Generator) Config() *openapi.Config

Config returns the OpenAPI configuration used by the Router.

func (*Generator) Delete added in v0.1.2 

func (g *Generator) Delete(path string, opts ...option.OperationOption) Route

Delete registers a new DELETE operation with the specified path and options.

func (*Generator) GenerateSchema 

func (g *Generator) GenerateSchema(formats ...string) ([]byte, error)

GenerateSchema generates the OpenAPI schema in the specified format (JSON or YAML).

By default, it generates YAML. If "json" is specified, it generates JSON.

func (*Generator) Get added in v0.1.2 

func (g *Generator) Get(path string, opts ...option.OperationOption) Route

Get registers a new GET operation with the specified path and options.

func (*Generator) Group added in v0.1.3 

func (g *Generator) Group(pattern string, opts ...option.GroupOption) Router

Group creates a new sub-router with the specified prefix and options.

func (*Generator) Head added in v0.1.2 

func (g *Generator) Head(path string, opts ...option.OperationOption) Route

Head registers a new HEAD operation with the specified path and options.

func (*Generator) Options added in v0.1.2 

func (g *Generator) Options(path string, opts ...option.OperationOption) Route

Options registers a new OPTIONS operation with the specified path and options.

func (*Generator) Patch added in v0.1.2 

func (g *Generator) Patch(path string, opts ...option.OperationOption) Route

Patch registers a new PATCH operation with the specified path and options.

func (*Generator) Post added in v0.1.2 

func (g *Generator) Post(path string, opts ...option.OperationOption) Route

Post registers a new POST operation with the specified path and options.

func (*Generator) Put added in v0.1.2 

func (g *Generator) Put(path string, opts ...option.OperationOption) Route

Put registers a new PUT operation with the specified path and options.

func (*Generator) Route added in v0.1.3 

func (g *Generator) Route(pattern string, fn func(router Router), opts ...option.GroupOption) Router

Route registers a new route with the specified pattern and function.

The function receives a Router instance to define sub-routes.

func (*Generator) Trace added in v0.1.2 

func (g *Generator) Trace(path string, opts ...option.OperationOption) Route

Trace registers a new TRACE operation with the specified path and options.

func (*Generator) Use added in v0.1.3 

func (g *Generator) Use(opts ...option.GroupOption) Router

Use applies the provided options to the router.

func (*Generator) Validate added in v0.1.2 

func (g *Generator) Validate() error

Validate checks if the generated OpenAPI specification is valid.

func (*Generator) WriteSchemaTo 

func (g *Generator) WriteSchemaTo(path string) error

WriteSchemaTo writes the OpenAPI schema to the specified file path.

The file format is determined by the file extension: ".json" for JSON and ".yaml" for YAML.

type Route added in v0.1.3 

type Route interface {
	// With applies the provided operation options to the route.
	With(opts ...option.OperationOption) Route
}

Route defines a method for creating a new route with the specified options.

type Router added in v0.1.3 

type Router interface {
	// Get registers a new GET operation with the specified path and options.
	Get(path string, opts ...option.OperationOption) Route
	// Post registers a new POST operation with the specified path and options.
	Post(path string, opts ...option.OperationOption) Route
	// Put registers a new PUT operation with the specified path and options.
	Put(path string, opts ...option.OperationOption) Route
	// Delete registers a new DELETE operation with the specified path and options.
	Delete(path string, opts ...option.OperationOption) Route
	// Patch registers a new PATCH operation with the specified path and options.
	Patch(path string, opts ...option.OperationOption) Route
	// Options registers a new OPTIONS operation with the specified path and options.
	Options(path string, opts ...option.OperationOption) Route
	// Head registers a new HEAD operation with the specified path and options.
	Head(path string, opts ...option.OperationOption) Route
	// Add registers a new operation with the specified method and path.
	Add(method, path string, opts ...option.OperationOption) Route
	// Trace registers a new TRACE operation with the specified path and options.
	Trace(path string, opts ...option.OperationOption) Route

	// Route registers a new route with the specified pattern and function.
	// The function receives a Router instance to define sub-routes.
	Route(pattern string, fn func(router Router), opts ...option.GroupOption) Router
	// Group creates a new sub-router with the specified prefix and options.
	Group(pattern string, opts ...option.GroupOption) Router
	// Use applies the provided options to the router.
	Use(opts ...option.GroupOption) Router
}

Router is an interface that defines methods for registering routes and operations in an OpenAPI specification. It allows for defining HTTP methods, paths, and operation options.

type SpecError added in v0.1.2 

type SpecError struct {
	// contains filtered or unexported fields
}

SpecError is a thread-safe error collector for OpenAPI specifications.

func (*SpecError) Error added in v0.1.2 

func (se *SpecError) Error() string

Error implements the error interface for SpecError.

func (*SpecError) Errors added in v0.1.2 

func (se *SpecError) Errors() []error

Errors returns a slice of collected errors.

func (*SpecError) HasErrors added in v0.1.2 

func (se *SpecError) HasErrors() bool

HasErrors checks if there are any collected errors.

Source Files

View all Source files

Directories

Path Synopsis
adapter
chiopenapi module
echoopenapi module
fiberopenapi module
ginopenapi module
httpopenapi module
httprouteropenapi module
muxopenapi module
adapters
chiopenapi module
echoopenapi module
fiberopenapi module
ginopenapi module
httpopenapi module
internal
mapper
module
specui module
pkg
debuglog
testutil
util

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.