gswag

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Apr 10, 2026 License: MIT Imports: 27 Imported by: 0

README

gswag

CI Go Report Card Go Reference

Generate OpenAPI 3.0 specs directly from your Ginkgo integration tests.

Inspired by rswag: define API docs alongside executable tests using a nested DSL.

How it works

gswag wraps Ginkgo containers (Path, Get/Post/..., Response, RunTest).

  1. During test tree construction, it records operation metadata (path, method, params, schemas, security).
  2. During test execution, RunTest makes a real HTTP request against your test server.
  3. Responses are asserted with Gomega and used to infer/capture examples when configured.
  4. WriteSpec() serializes the in-memory OpenAPI document.

Installation

go get github.com/oaswrap/gswag

Requires Go 1.24+.

Quick Start

1. Configure suite and server

Scaffold a suite file with gswag init, or write it manually:

// suite_test.go
package api_test

import (
    "net/http/httptest"
    "testing"

    . "github.com/oaswrap/gswag"
    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
)

var testServer *httptest.Server

func TestAPI(t *testing.T) {
    RegisterFailHandler(Fail)
    RunSpecs(t, "API Suite")
}

var _ = BeforeSuite(func() {
    Init(&Config{
        Title:      "My API",
        Version:    "1.0.0",
        OutputPath: "./docs/openapi.yaml",
        SecuritySchemes: map[string]SecuritySchemeConfig{
            "bearerAuth": BearerJWT(),
        },
    })

    testServer = httptest.NewServer(NewRouter())
    SetTestServer(testServer)
})

var _ = AfterSuite(func() {
    testServer.Close()
    Expect(WriteSpec()).To(Succeed())
})

Or use the RegisterSuiteHandlers helper (single-process suites):

func TestAPI(t *testing.T) {
    gswag.RegisterSuiteHandlers(&gswag.Config{
        Title:      "My API",
        Version:    "1.0.0",
        OutputPath: "./docs/openapi.yaml",
    })
    RegisterFailHandler(Fail)
    RunSpecs(t, "API Suite")
}
2. Write API specs with the DSL
// users_test.go
package api_test

import (
    "net/http"

    . "github.com/oaswrap/gswag"
    . "github.com/onsi/gomega"
)

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

var _ = Path("/users/{id}", func() {
    Get("Get user by ID", func() {
        Tag("users")
        OperationID("getUserByID")
        BearerAuth()
        Parameter("id", PathParam, String)

        Response(200, "user found", func() {
            ResponseSchema(new(User))
            SetParam("id", "1")

            RunTest(func(resp *http.Response) {
                Expect(resp).To(HaveStatus(http.StatusOK))
                Expect(resp).To(ContainJSONKey("id"))
            })
        })
    })
})

DSL Reference

Path and operations
Path("/users", func() {
    Get("List users", func() { ... })
    Post("Create user", func() { ... })
})

Path("/users/{id}", func() {
    Get("Get user", func() { ... })
    Put("Replace user", func() { ... })
    Patch("Update user", func() { ... })
    Delete("Delete user", func() { ... })
})
Operation metadata
Tag("users", "admin")
Description("Returns one user")
OperationID("getUser")
Deprecated()
Hidden() // run test, but do not add the operation to the spec
Security
BearerAuth()                    // uses "bearerAuth"
Security("apiKey")             // custom scheme
// Security("oauth2", "scope") // with scopes if needed
Parameters
Parameter("id", PathParam, String)
Parameter("limit", QueryParam, Integer)
Parameter("X-Request-ID", HeaderParam, String)

You can also define typed query params:

type ListQuery struct {
    Search string `query:"search"`
    Page   int    `query:"page"`
}

QueryParamStruct(new(ListQuery))
Request and response schema
RequestBody(new(CreateUserRequest))

Response(201, "created", func() {
    ResponseSchema(new(User))
    ResponseHeader("X-Rate-Limit", "")

    SetBody(&CreateUserRequest{Name: "Alice"})
    SetHeader("X-Trace-ID", "abc")
    SetQueryParam("verbose", "true")

    RunTest()
})

Request value setters (for execution):

  • SetParam(name, value)
  • SetQueryParam(name, value)
  • SetHeader(name, value)
  • SetBody(body)
  • SetRawBody([]byte, contentType)
Content types

By default gswag documents request bodies as application/json. Use Consumes and Produces to override:

Post("Upload file", func() {
    Consumes("multipart/form-data")
    Produces("application/json")
    RequestBody(new(UploadForm))

    Response(200, "uploaded", func() {
        SetRawBody(formData, "multipart/form-data")
        RunTest(...)
    })
})

Produces accepts multiple types when an endpoint can serve different formats:

Get("Export data", func() {
    Produces("application/json", "text/csv")
    ...
})
Shared request setup with BeforeRequest

Use BeforeRequest (a thin BeforeEach wrapper) to share SetParam, SetHeader, or SetBody calls across multiple Response blocks — similar to let in rswag:

Get("Get order", func() {
    BeforeRequest(func() {
        SetHeader("Authorization", "Bearer test-token")
    })

    Response(200, "found", func() {
        SetParam("id", "42")
        RunTest(...)
    })

    Response(404, "not found", func() {
        SetParam("id", "999")
        RunTest(...)
    })
})

Note: BeforeRequest runs during test execution (Ginkgo BeforeEach), so it is suited for values that can only be determined at runtime. Static values (known at test-tree build time) should be set directly inside the Response block.

Config

Init(&Config{
    Title:           "My API",           // required
    Version:         "1.0.0",            // required
    Description:     "Public API",
    TermsOfService:  "https://example.com/terms",
    Contact: &ContactConfig{
        Name:  "API Team",
        URL:   "https://example.com/support",
        Email: "api@example.com",
    },
    License: &LicenseConfig{
        Name: "Apache 2.0",
        URL:  "https://www.apache.org/licenses/LICENSE-2.0.html",
    },
    ExternalDocs: &ExternalDocsConfig{
        Description: "More docs",
        URL:         "https://example.com/docs",
    },
    Tags: []TagConfig{
        {Name: "users", Description: "User operations"},
    },
    OutputPath:      "./docs/openapi.yaml", // default: ./docs/openapi.yaml
    OutputFormat:    YAML,                   // YAML or JSON
    Servers: []ServerConfig{
        {URL: "https://api.example.com", Description: "prod"},
    },
    ExcludePaths: []string{
        "/internal/*",
        "/admin/health",
    },
    SecuritySchemes: map[string]SecuritySchemeConfig{
        "bearerAuth": BearerJWT(),
        "apiKey":     APIKeyHeader("X-API-Key"),
        "oauth2":     OAuth2Implicit("https://example.com/oauth/authorize", map[string]string{
            "read:users":  "read users",
            "write:users": "modify users",
        }),
    },

    EnforceResponseValidation: true,
    ValidationMode:            "warn", // "fail" (default) or "warn"

    CaptureExamples: true,
    MaxExampleBytes: 0, // 0 means default cap of 16384 bytes; set >0 to override
    Sanitizer: func(b []byte) []byte {
        return b // redact sensitive data here
    },

    MergeTimeout: 60 * time.Second, // how long MergeAndWriteSpec waits for slow nodes (default 30s)
})

ExcludePaths supports exact path matches and simple prefix patterns ending in *. Excluded operations are still executed by tests when you hit them through RunTest; they are only omitted from spec generation.

Security helpers:

  • BearerJWT()
  • APIKeyHeader(name)
  • APIKeyQuery(name)
  • APIKeyCookie(name)
  • OAuth2Implicit(authURL, scopes)

Gomega Matchers

Matchers operate on *http.Response (the object passed to RunTest callback):

  • HaveStatus(code)
  • HaveStatusInRange(lo, hi)
  • HaveHeader(key, value)
  • HaveJSONBody(expected)
  • ContainJSONKey(key)
  • MatchJSONSchema(model)
  • HaveNonEmptyBody()

Example:

RunTest(func(resp *http.Response) {
    Expect(resp).To(HaveStatus(200))
    Expect(resp).To(HaveHeader("Content-Type", "application/json"))
    Expect(resp).To(ContainJSONKey("id"))
})

Validation

Validate in-memory spec
issues := ValidateSpec()
for _, issue := range issues {
    fmt.Println(issue.String())
}
Validate file
issues, err := ValidateSpecFile("docs/openapi.yaml")
Write then validate
if err := WriteAndValidateSpec(); err != nil {
    // err wraps ErrSpecInvalid when error-level issues exist
    panic(err)
}

Validation highlights:

  • info.title and info.version required (error)
  • empty paths (warning)
  • operation missing summary/tags (warning)
  • undeclared security scheme references (error)

Parallel Ginkgo Support

For ginkgo -p, each parallel process writes a partial spec and process 1 merges them all.

func TestAPI(t *testing.T) {
    gswag.RegisterParallelSuiteHandlers(&gswag.Config{
        Title:      "My API",
        Version:    "1.0.0",
        OutputPath: "./docs/openapi.yaml",
    }, "./tmp/gswag") // partialDir shared by all nodes
    RegisterFailHandler(Fail)
    RunSpecs(t, "API Suite")
}

RegisterParallelSuiteHandlers uses Ginkgo's SynchronizedAfterSuite internally, which guarantees that node 1 only merges after all other nodes have finished writing their partial files.

Option B — manual SynchronizedAfterSuite
var _ = SynchronizedAfterSuite(func() {
    // Runs on every node — write this node's partial spec.
    Expect(gswag.WritePartialSpec(GinkgoParallelProcess(), "./tmp/gswag")).To(Succeed())
}, func() {
    // Runs only on node 1, after all other nodes finish the block above.
    suiteCfg, _ := GinkgoConfiguration()
    Expect(gswag.MergeAndWriteSpec(suiteCfg.ParallelTotal, "./tmp/gswag")).To(Succeed())
})

Partial files are written as ./tmp/gswag/node-N.json. MergeAndWriteSpec polls for each file with a configurable timeout (default 30 s, override via Config.MergeTimeout).

Documentation

Overview

Package gswag generates OpenAPI 3.0 specifications from Ginkgo integration tests.

Inspired by rswag (Ruby), gswag lets you write your API tests once and get a fully generated openapi.yaml for free — no annotations, no code generation.

Quick start

  1. Call Init in your Ginkgo BeforeSuite with a Config.
  2. Call SetTestServer in BeforeSuite after starting your httptest.Server.
  3. Describe endpoints with the DSL: Path, Get, Post, Put, Patch, Delete.
  4. Declare parameters with Parameter, RequestBody and response schemas with ResponseSchema.
  5. Execute requests and assert with RunTest.
  6. Call WriteSpec in AfterSuite to emit the spec file.

Example: 

var _ = BeforeSuite(func() {
    gswag.Init(&gswag.Config{
        Title:      "My API",
        Version:    "1.0.0",
        OutputPath: "./docs/openapi.yaml",
    })
    testServer = httptest.NewServer(myRouter)
    gswag.SetTestServer(testServer)
})

var _ = AfterSuite(func() {
    testServer.Close()
    Expect(gswag.WriteSpec()).To(Succeed())
})

var _ = Path("/api/users/{id}", func() {
    Get("Get user by ID", func() {
        Tag("users")
        Parameter("id", gswag.PathParam, gswag.String)

        Response(200, "user found", func() {
            ResponseSchema(new(User))
            SetParam("id", "1")
            RunTest(func(resp *http.Response) {
                Expect(resp.StatusCode).To(Equal(200))
            })
        })
    })
})

Index

Constants

View Source 
const (
	InPath   ParamLocation = "path"
	InQuery  ParamLocation = "query"
	InHeader ParamLocation = "header"
	InCookie ParamLocation = "cookie"

	// PathParam is a short alias for InPath.
	PathParam = InPath
	// QueryParam is a short alias for InQuery.
	QueryParam = InQuery
	// HeaderParam is a short alias for InHeader.
	HeaderParam = InHeader
	// CookieParam is a short alias for InCookie.
	CookieParam = InCookie
)

Variables

View Source 
var ErrSpecInvalid = errors.New("spec has validation errors")

ErrSpecInvalid is returned when the spec has at least one error-level issue.

Functions

func BearerAuth 

func BearerAuth()

BearerAuth adds a Bearer JWT security requirement to the current operation.

func BeforeRequest 

func BeforeRequest(fn func())

BeforeRequest registers a Ginkgo BeforeEach that runs before each RunTest It block inside the current operation or response. Use it to share SetParam, SetHeader, or SetBody calls across multiple Response blocks — similar to RSpec's let blocks in rswag. 

Get("Get user", func() {
    BeforeRequest(func() { SetParam("id", "42") })
    Response(200, "found", func() { RunTest(...) })
    Response(404, "missing", func() { RunTest(...) })
})

func Consumes 

func Consumes(contentType string)

Consumes sets the request body content-type for the current operation. Defaults to "application/json" when not called. Useful for multipart, form-encoded, or other non-JSON request bodies.

func ContainJSONKey 

func ContainJSONKey(key string) types.GomegaMatcher

ContainJSONKey succeeds when the response body is a JSON object containing the given key.

func Delete 

func Delete(summary string, fn func())

Delete declares a DELETE operation on the current path.

func Deprecated 

func Deprecated()

Deprecated marks the current operation as deprecated in the spec.

func Description 

func Description(desc string)

Description sets the description of the current operation.

func Get 

func Get(summary string, fn func())

Get declares a GET operation on the current path.

func HaveHeader 

func HaveHeader(key, value string) types.GomegaMatcher

HaveHeader succeeds when the response contains the given header with the expected value.

func HaveJSONBody 

func HaveJSONBody(expected any) types.GomegaMatcher

HaveJSONBody succeeds when the response body can be JSON-decoded and equals expected after a round-trip JSON normalisation.

func HaveNonEmptyBody 

func HaveNonEmptyBody() types.GomegaMatcher

HaveNonEmptyBody succeeds when the response body is not empty.

func HaveStatus 

func HaveStatus(expected int) types.GomegaMatcher

HaveStatus succeeds when the response has the expected HTTP status code.

func HaveStatusInRange 

func HaveStatusInRange(lo, hi int) types.GomegaMatcher

HaveStatusInRange succeeds when the status code is in [lo, hi] inclusive.

func Hidden 

func Hidden()

Hidden excludes the current operation from the generated spec while still allowing RunTest to execute the underlying HTTP request.

func Init 

func Init(cfg *Config)

Init initialises gswag with the given configuration. Call this once in your Ginkgo BeforeSuite.

func MatchJSONSchema 

func MatchJSONSchema(model any) types.GomegaMatcher

MatchJSONSchema succeeds when every key present in the model type is also present in the response JSON (structural validation — values are not compared).

func MergeAndWriteSpec 

func MergeAndWriteSpec(totalNodes int, dir string) error

MergeAndWriteSpec reads all partial spec files written by WritePartialSpec, merges their paths and schemas, then writes the final spec using the global config. This must only be called on node 1 after all other nodes have called WritePartialSpec.

It polls for each node's partial file until it appears, using the MergeTimeout from the global config (default 30 s). Use Ginkgo's SynchronizedAfterSuite to guarantee all nodes have finished writing before this is called.

func OperationID 

func OperationID(id string)

OperationID sets the operationId of the current operation.

func Parameter 

func Parameter(name string, in ParamLocation, typ SchemaType, opts ...ParameterOption)

Parameter declares a named parameter for the current operation.

func Patch 

func Patch(summary string, fn func())

Patch declares a PATCH operation on the current path.

func Path 

func Path(template string, fn func()) bool

Path wraps fn in a Ginkgo Describe node and pushes template onto the path stack. Use at package level with var _ = Path(...).

func Post 

func Post(summary string, fn func())

Post declares a POST operation on the current path.

func Produces 

func Produces(contentTypes ...string)

Produces sets the accepted response content-types for the current operation. Defaults to "application/json" when not called. Multiple content types may be specified to document endpoints that serve e.g. both JSON and XML.

func Put 

func Put(summary string, fn func())

Put declares a PUT operation on the current path.

func QueryParamStruct 

func QueryParamStruct(v any)

QueryParamStruct registers a struct with query tags as query parameter schemas.

func RegisterParallelSuiteHandlers 

func RegisterParallelSuiteHandlers(cfg *Config, partialDir string)

RegisterParallelSuiteHandlers registers suite hooks suitable for parallel Ginkgo runs (`ginkgo -p`). Each node writes a partial spec; node 1 then merges them all into the final output.

partialDir is a temporary directory used to store per-node partial specs. It must be accessible by all parallel nodes (i.e. on a shared filesystem). 

func TestAPI(t *testing.T) {
    gswag.RegisterParallelSuiteHandlers(&gswag.Config{...}, "./tmp/gswag")
    gomega.RegisterFailHandler(gomega.Fail)
    ginkgo.RunSpecs(t, "API Suite")
}

func RegisterSuiteHandlers 

func RegisterSuiteHandlers(cfg *Config)

RegisterSuiteHandlers registers BeforeSuite and AfterSuite hooks that initialise gswag and write the spec on suite completion.

Call this from your TestXxx function or at package init, passing the same Config you would pass to Init. For parallel test runs use RegisterParallelSuiteHandlers instead. 

func TestAPI(t *testing.T) {
    gswag.RegisterSuiteHandlers(&gswag.Config{...})
    gomega.RegisterFailHandler(gomega.Fail)
    ginkgo.RunSpecs(t, "API Suite")
}

func RequestBody 

func RequestBody(model any)

RequestBody sets a typed struct as the request body schema for the current operation.

func Response 

func Response(status int, description string, fn func())

Response declares a response for the current operation and wraps fn in a Ginkgo Context.

func ResponseHeader 

func ResponseHeader(name string, model any)

ResponseHeader declares a response header schema for the current response.

func ResponseSchema 

func ResponseSchema(model any)

ResponseSchema sets the expected response body schema model for the current response.

func RunTest 

func RunTest(fn ...func(*http.Response))

RunTest registers a Ginkgo It block that fires the HTTP request and calls fn if provided.

func Security 

func Security(schemeName string, scopes ...string)

Security adds a named security requirement to the current operation.

func SetBody 

func SetBody(body any)

SetBody sets a typed request body for the current test case.

func SetHeader 

func SetHeader(name, value string)

SetHeader sets a request header for the current test case.

func SetParam 

func SetParam(name, value string)

SetParam sets a path parameter value for the current test case.

func SetQueryParam 

func SetQueryParam(name, value string)

SetQueryParam sets a query parameter value for the current test case.

func SetRawBody 

func SetRawBody(body []byte, contentType string)

SetRawBody sets a raw request body for the current test case.

func SetTestServer 

func SetTestServer(target any)

SetTestServer registers the HTTP target used by RunTest.

func Tag 

func Tag(tags ...string)

Tag appends one or more tags to the current operation.

func WriteAndValidateSpec 

func WriteAndValidateSpec() error

WriteAndValidateSpec writes the spec and then validates it. Returns ErrSpecInvalid (wrapping the issue list) if any errors are found.

func WritePartialSpec 

func WritePartialSpec(nodeIndex int, dir string) error

WritePartialSpec serialises the current collector's spec to a file inside dir. The file is named after nodeIndex (1-based) so that the merge step can discover all node outputs without coordination.

Call this in AfterSuite on every parallel Ginkgo node before shutting down: 

var _ = AfterSuite(func() {
    testServer.Close()
    Expect(gswag.WritePartialSpec(GinkgoParallelProcess(), "./tmp/gswag")).To(Succeed())
    if GinkgoParallelProcess() == 1 {
        Expect(gswag.MergeAndWriteSpec(GinkgoProcs(), "./tmp/gswag")).To(Succeed())
    }
})

func WriteSpec 

func WriteSpec() error

WriteSpec serialises the collected spec to the path and format configured via Init.

func WriteSpecTo 

func WriteSpecTo(path string, format OutputFormat) error

WriteSpecTo serialises the collected spec to a specific path and format.

Types

type Config 

type Config struct {
	Title          string
	Version        string
	Description    string
	TermsOfService string
	Contact        *ContactConfig
	License        *LicenseConfig
	ExternalDocs   *ExternalDocsConfig
	Tags           []TagConfig
	OutputPath     string // default: "./docs/openapi.yaml"
	OutputFormat   OutputFormat
	Servers        []ServerConfig
	// ExcludePaths omits matching operations from the generated spec.
	// Entries support exact path matches and simple prefix patterns ending in '*'.
	ExcludePaths    []string
	SecuritySchemes map[string]SecuritySchemeConfig
	// EnforceResponseValidation enables test-time validation of actual HTTP
	// responses against the declared or inferred response schema. When true,
	// validation behavior is controlled by ValidationMode.
	EnforceResponseValidation bool
	// ValidationMode controls runtime behavior when a validation error occurs.
	// Allowed values: "fail" (default) — cause test to fail/panic; "warn" —
	// write a warning to stderr and continue.
	ValidationMode string
	// CaptureExamples enables storing request and response bodies as examples
	// in the generated spec. When true, request/response bodies observed at
	// test time are attached to the OpenAPI `examples` or `example` fields.
	CaptureExamples bool
	// MaxExampleBytes caps the number of bytes stored for any single example.
	// A value of 0 means no cap. Defaults to 16384 (16 KiB) when zero.
	MaxExampleBytes int
	// Sanitizer is an optional hook to transform or redact example bytes before
	// they are stored in the spec. If nil, examples are recorded verbatim (subject to cap).
	Sanitizer func([]byte) []byte
	// StripDefinitionNamePrefixes lists definition name prefixes that should be
	// removed from reflected JSON Schema definition names. Applied when building
	// reflectors so component schema names are cleaner.
	StripDefinitionNamePrefixes []string
	// InlineRefs controls whether JSON Schema reflector inlines referenced
	// types instead of creating component references. When true, schemas
	// are attempted to be inlined where possible.
	InlineRefs bool
	// TypeMappings holds list of type substitutions to apply to the jsonschema
	// reflector. Each mapping calls `AddTypeMapping(src, dst)`.
	TypeMappings []TypeMapping
	// MergeTimeout is the maximum duration MergeAndWriteSpec will wait for each
	// parallel node's partial spec file to appear. Defaults to 30 s when zero.
	MergeTimeout time.Duration
}

Config holds global settings for gswag.

type ContactConfig 

type ContactConfig struct {
	Name  string
	URL   string
	Email string
}

ContactConfig describes OpenAPI info.contact metadata.

type ExternalDocsConfig 

type ExternalDocsConfig struct {
	Description string
	URL         string
}

ExternalDocsConfig describes OpenAPI external documentation metadata.

type LicenseConfig 

type LicenseConfig struct {
	Name string
	URL  string
}

LicenseConfig describes OpenAPI info.license metadata.

type OutputFormat 

type OutputFormat int

OutputFormat controls the serialization format of the generated spec. 

const (
	YAML OutputFormat = iota
	JSON
)

type ParamLocation 

type ParamLocation string

ParamLocation indicates where a parameter appears in an HTTP request.

type ParameterOption 

type ParameterOption func(*dslParam)

ParameterOption customizes an operation parameter declared by Parameter.

func ParamDefault 

func ParamDefault(value any) ParameterOption

ParamDefault sets the parameter default value in the generated schema.

func ParamEnum 

func ParamEnum(values ...any) ParameterOption

ParamEnum constrains parameter values to the provided enum values.

func ParamExplode 

func ParamExplode(explode bool) ParameterOption

ParamExplode controls the OpenAPI explode flag for the parameter.

func ParamRequired 

func ParamRequired(required bool) ParameterOption

ParamRequired marks a parameter as required/optional in the generated spec.

type SchemaType 

type SchemaType string

SchemaType is the OpenAPI primitive type for a declared parameter or schema. 

const (
	String  SchemaType = "string"
	Integer SchemaType = "integer"
	Number  SchemaType = "number"
	Boolean SchemaType = "boolean"
	Object  SchemaType = "object"
	Array   SchemaType = "array"
)

type SecuritySchemeConfig 

type SecuritySchemeConfig struct {
	Type         string // "http", "apiKey", "oauth2", "openIdConnect"
	Scheme       string // e.g. "bearer"
	BearerFormat string // e.g. "JWT"
	In           string // "header", "query", "cookie" (apiKey)
	Name         string // header/query/cookie parameter name (apiKey)
	// OAuth2 implicit flow fields.
	AuthorizationURL string            // e.g. https://petstore3.swagger.io/oauth/authorize
	RefreshURL       string            // optional refresh URL
	Scopes           map[string]string // scope -> description
}

SecuritySchemeConfig describes a named security scheme.

func APIKeyCookie 

func APIKeyCookie(cookieName string) SecuritySchemeConfig

APIKeyCookie returns a SecuritySchemeConfig for an API key passed in a cookie.

func APIKeyHeader 

func APIKeyHeader(headerName string) SecuritySchemeConfig

APIKeyHeader returns a SecuritySchemeConfig for an API key passed in a header.

func APIKeyQuery 

func APIKeyQuery(paramName string) SecuritySchemeConfig

APIKeyQuery returns a SecuritySchemeConfig for an API key passed in a query param.

func BearerJWT 

func BearerJWT() SecuritySchemeConfig

BearerJWT returns a SecuritySchemeConfig for an HTTP Bearer JWT scheme.

func OAuth2Implicit 

func OAuth2Implicit(authURL string, scopes map[string]string) SecuritySchemeConfig

OAuth2Implicit returns a SecuritySchemeConfig for an OAuth2 implicit flow.

type ServerConfig 

type ServerConfig struct {
	URL         string
	Description string
}

ServerConfig describes an OpenAPI server entry.

type SpecCollector 

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

SpecCollector accumulates OpenAPI operations from test executions in a thread-safe manner.

func (*SpecCollector) Register 

func (sc *SpecCollector) Register(b *requestBuilder, res *recordedResponse)

Register adds an operation to the spec based on the requestBuilder metadata and the actual recordedResponse. Safe to call concurrently.

func (*SpecCollector) RegisterDSLOperation 

func (sc *SpecCollector) RegisterDSLOperation(op *dslOp)

RegisterDSLOperation registers an operation declared via the rswag-style DSL. Called from a Ginkgo BeforeAll node so that spec registration happens once per operation, before any RunTest It blocks execute.

type TagConfig 

type TagConfig struct {
	Name         string
	Description  string
	ExternalDocs *ExternalDocsConfig
}

TagConfig describes a top-level OpenAPI tag with optional metadata.

type TypeMapping 

type TypeMapping struct {
	Src any
	Dst any
}

TypeMapping describes a substitution between two Go types for JSON Schema reflection. Provide a sample `Src` value (or a type) and a `Dst` value to map to.

type ValidationIssue 

type ValidationIssue struct {
	Severity string // "error" or "warning"
	Path     string // e.g. "paths./users.get"
	Message  string
}

ValidationIssue describes a single spec problem.

func ValidateSpec 

func ValidateSpec() []ValidationIssue

ValidateSpec runs structural validation on the collected spec and returns any issues found. Errors must be fixed for a valid spec; warnings are informational.

func ValidateSpecFile 

func ValidateSpecFile(path string) ([]ValidationIssue, error)

ValidateSpecFile reads a YAML or JSON spec file and runs structural validation.

func (ValidationIssue) String 

func (v ValidationIssue) String() string

Source Files

View all Source files

Directories

Path Synopsis
internal
golden
Package golden provides helpers for golden-file based testing.
 Package golden provides helpers for golden-file based testing.
output
schemautil
Package schemautil provides best-effort JSON → OpenAPI schema inference.
 Package schemautil provides best-effort JSON → OpenAPI schema inference.
test
all_methods
basic_data
content_type
custom_types
deprecated
examples
exclude_hidden
inline_refs
nested_paths
petstore
query_struct
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.