Documentation
¶
Overview ¶
Package corpusutil provides utilities for loading and managing the integration test corpus of real-world public OpenAPI specifications.
The corpus includes 10 carefully selected specifications spanning:
- OAS versions: 2.0, 3.0.0, 3.0.3, 3.0.4, 3.1.0
- Formats: JSON and YAML
- Sizes: From 20KB (Petstore) to 34MB (Microsoft Graph)
- Domains: FinTech, Developer Tools, Enterprise, etc.
Usage ¶
Tests should use the SkipIfNotCached helper to gracefully skip when corpus files are not available:
func TestCorpus_Parse(t *testing.T) {
for _, spec := range corpusutil.GetSpecs(false) {
t.Run(spec.Name, func(t *testing.T) {
corpusutil.SkipIfNotCached(t, spec)
// ... test implementation
})
}
}
Downloading the Corpus ¶
Run `make corpus-download` to fetch all specifications to testdata/corpus/. These files are not committed to the repository.
Index ¶
- Variables
- func CorpusDir() string
- func SkipIfHasParsingIssues(t testing.TB, spec SpecInfo)
- func SkipIfNotCached(t testing.TB, spec SpecInfo)
- func SkipLargeInShortMode(t testing.TB, spec SpecInfo)
- type SpecInfo
- func GetByName(name string) *SpecInfo
- func GetInvalidSpecs(includeLarge bool) []SpecInfo
- func GetLargeSpecs() []SpecInfo
- func GetOAS2Specs() []SpecInfo
- func GetOAS3Specs(includeLarge bool) []SpecInfo
- func GetParseableSpecs(includeLarge bool) []SpecInfo
- func GetSpecs(includeLarge bool) []SpecInfo
- func GetValidSpecs(includeLarge bool) []SpecInfo
Constants ¶
This section is empty.
Variables ¶
var Corpus = []SpecInfo{ { Name: "Petstore", Filename: "petstore-swagger.json", URL: "https://petstore.swagger.io/v2/swagger.json", OASVersion: "2.0", Format: "json", ExpectedValid: true, ExpectedErrors: 0, IsLarge: false, SizeBytes: 20_000, }, { Name: "DigitalOcean", Filename: "digitalocean-public.v2.yaml", URL: "https://api-engineering.nyc3.digitaloceanspaces.com/spec-ci/DigitalOcean-public.v2.yaml", OASVersion: "3.0.0", Format: "yaml", ExpectedValid: false, ExpectedErrors: 496, IsLarge: false, SizeBytes: 2_500_000, }, { Name: "Asana", Filename: "asana-oas.yaml", URL: "https://raw.githubusercontent.com/Asana/openapi/master/defs/asana_oas.yaml", OASVersion: "3.0.0", Format: "yaml", ExpectedValid: false, ExpectedErrors: 302, IsLarge: false, SizeBytes: 405_000, }, { Name: "GoogleMaps", Filename: "google-maps-platform.json", URL: "https://raw.githubusercontent.com/googlemaps/openapi-specification/main/dist/google-maps-platform-openapi3.json", OASVersion: "3.0.3", Format: "json", ExpectedValid: true, ExpectedErrors: 0, IsLarge: false, SizeBytes: 500_000, }, { Name: "USNWS", Filename: "nws-openapi.json", URL: "https://api.weather.gov/openapi.json", OASVersion: "3.0.3", Format: "json", ExpectedValid: false, ExpectedErrors: 44, IsLarge: false, SizeBytes: 800_000, }, { Name: "Plaid", Filename: "plaid-2020-09-14.yml", URL: "https://raw.githubusercontent.com/plaid/plaid-openapi/master/2020-09-14.yml", OASVersion: "3.0.0", Format: "yaml", ExpectedValid: false, ExpectedErrors: 101, IsLarge: false, SizeBytes: 1_200_000, }, { Name: "Discord", Filename: "discord-openapi.json", URL: "https://raw.githubusercontent.com/discord/discord-api-spec/main/specs/openapi.json", OASVersion: "3.1.0", Format: "json", ExpectedValid: true, ExpectedErrors: 0, IsLarge: false, SizeBytes: 3_000_000, }, { Name: "GitHub", Filename: "github-api.json", URL: "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", OASVersion: "3.0.3", Format: "json", ExpectedValid: false, ExpectedErrors: 2224, IsLarge: false, SizeBytes: 5_000_000, }, { Name: "Stripe", Filename: "stripe-spec3.json", URL: "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json", OASVersion: "3.0.0", Format: "json", ExpectedValid: true, ExpectedErrors: 0, IsLarge: true, SizeBytes: 14_000_000, }, { Name: "MicrosoftGraph", Filename: "msgraph-openapi.yaml", URL: "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml", OASVersion: "3.0.4", Format: "yaml", ExpectedValid: true, ExpectedErrors: 0, IsLarge: true, SizeBytes: 34_000_000, }, }
Corpus defines all 10 public specifications for integration testing. Specifications are ordered by size (smallest first) for faster test feedback.
Functions ¶
func CorpusDir ¶
func CorpusDir() string
CorpusDir returns the absolute path to the corpus directory.
func SkipIfHasParsingIssues ¶
SkipIfHasParsingIssues skips specs that have known parsing issues.
func SkipIfNotCached ¶
SkipIfNotCached skips the test if the corpus file is not available locally.
func SkipLargeInShortMode ¶
SkipLargeInShortMode skips large specs when running with -short flag.
Types ¶
type SpecInfo ¶
type SpecInfo struct {
Name string // Human-readable name (e.g., "Stripe")
Filename string // Local filename in testdata/corpus/
URL string // Remote source URL
OASVersion string // Expected OAS version (e.g., "3.0.0", "2.0")
Format string // "json" or "yaml"
ExpectedValid bool // Whether strict validation should pass
ExpectedErrors int // Approximate error count if invalid (for tolerance)
IsLarge bool // True if file size >5MB
SizeBytes int64 // Approximate file size in bytes
HasParsingIssues bool // True if spec uses features our parser doesn't handle
}
SpecInfo contains metadata about a corpus specification.
func GetInvalidSpecs ¶
GetInvalidSpecs returns only specs expected to fail validation.
func GetLargeSpecs ¶
func GetLargeSpecs() []SpecInfo
GetLargeSpecs returns only large (>5MB) specifications.
func GetOAS2Specs ¶
func GetOAS2Specs() []SpecInfo
GetOAS2Specs returns OAS 2.0 (Swagger) specifications.
func GetOAS3Specs ¶
GetOAS3Specs returns OAS 3.x specifications.
func GetParseableSpecs ¶
GetParseableSpecs returns only specs without known parsing issues.
func GetValidSpecs ¶
GetValidSpecs returns only specs expected to pass validation.
func (SpecInfo) GetLocalPath ¶
GetLocalPath returns the absolute path to the cached spec file.
func (SpecInfo) IsAvailable ¶
IsAvailable checks if the spec is cached locally.
Source Files