README
¶
oaswrap/spec
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() {
r := spec.NewGenerator(
option.WithTitle("My API"),
option.WithVersion("1.0.0"),
)
r.Post("/login",
option.Summary("User Login"),
option.Description("Logs in a user and returns a token"),
option.Request(new(LoginRequest)),
option.Response(200, new(TokenResponse)),
)
if err := r.Validate(); err != nil {
log.Fatal(err)
}
_ = r.WriteSchemaTo("openapi.yaml")
}
type LoginRequest struct {
Username string `json:"username" required:"true"`
Password string `json:"password" required:"true"`
}
type TokenResponse struct {
AccessToken string `json:"access_token"`
}
📚 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 ¶
- type Generator
- func (g *Generator) Add(method, path string, opts ...option.OperationOption)
- func (g *Generator) Config() *openapi.Config
- func (g *Generator) Delete(path string, opts ...option.OperationOption)
- func (g *Generator) GenerateSchema(formats ...string) ([]byte, error)
- func (g *Generator) Get(path string, opts ...option.OperationOption)
- func (g *Generator) Head(path string, opts ...option.OperationOption)
- func (g *Generator) Options(path string, opts ...option.OperationOption)
- func (g *Generator) Patch(path string, opts ...option.OperationOption)
- func (g *Generator) Post(path string, opts ...option.OperationOption)
- func (g *Generator) Put(path string, opts ...option.OperationOption)
- func (g *Generator) Trace(path string, opts ...option.OperationOption)
- func (g *Generator) Validate() error
- func (g *Generator) WriteSchemaTo(path string) error
- type SpecError
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 responsible for generating OpenAPI documentation.
func NewGenerator ¶
func NewGenerator(opts ...option.OpenAPIOption) *Generator
NewGenerator creates a new Generator instance with the provided configuration.
func (*Generator) Add ¶ added in v0.1.2
func (g *Generator) Add(method, path string, opts ...option.OperationOption)
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
Config returns the OpenAPI configuration used by the Generator.
func (*Generator) Delete ¶ added in v0.1.2
func (g *Generator) Delete(path string, opts ...option.OperationOption)
Delete registers a new DELETE operation with the specified path and options.
func (*Generator) GenerateSchema ¶
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)
Get registers a new GET operation with the specified path and options.
func (*Generator) Head ¶ added in v0.1.2
func (g *Generator) Head(path string, opts ...option.OperationOption)
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)
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)
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)
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)
Put registers a new PUT operation with the specified path and options.
func (*Generator) Trace ¶ added in v0.1.2
func (g *Generator) Trace(path string, opts ...option.OperationOption)
Trace registers a new TRACE operation with the specified path and options.
func (*Generator) Validate ¶ added in v0.1.2
Validate checks if the generated OpenAPI specification is valid.
func (*Generator) WriteSchemaTo ¶
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 SpecError ¶ added in v0.1.2
type SpecError struct {
// contains filtered or unexported fields
}
SpecError is a thread-safe error collector for OpenAPI specifications.
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
|
|
|
module
|
|
|
specui
module
|
|
|
pkg
|
|