feat: add oastools builder for OAS 2.0 and 3.x document generation

[erraggy]

Summary

• Adds new BuildOAS2 and BuildOAS3 functions that generate OpenAPI 2.0 and 3.x documents using the oastools library
• Supports OpenAPI versions 3.2.0, 3.1.x, 3.0.x, and 2.0 (Swagger)
• Introduces configurable schema naming strategies and generic type naming options
• Adds semantic deduplication support for consolidating identical schemas
• Modernizes tooling with updated .golangci.yml (v2 format) and enhanced Makefile
• Updates README with comprehensive documentation for new API

New Features

Feature	Description
BuildOAS3(config)	Build OpenAPI 3.x documents with version selection
BuildOAS2(config)	Build OpenAPI 2.0 documents using oastools
Schema Naming Strategies	Control how Go types become schema names (TypeOnly, PascalCase, etc.)
Generic Naming Strategies	Format generic type parameters (Underscore, Of, For, AngleBrackets)
Semantic Deduplication	Consolidate structurally identical schemas
Post-build Handlers	Customize documents via PostBuildOAS2Handler / PostBuildOAS3Handler

Test plan

• All existing tests pass
• New oastools_builder_test.go covers OAS 2.0 and 3.x generation
• Rebased on latest v2 branch to incorporate upstream changes

🤖 Generated with Claude Code

Notes

I worked to provide all that's required for producing ALL OAS versions in my oastools library, and then used Claude Code and Opus 4.5 to implement this while keeping full backward compatibility. Please consider this as a replacement for the go-openapi project of libraries, since they've stated no willingness to support OAS3.x.

Resolves

• Fixes Is there a way to generate openapi v3? #76
• Addresses would you migrate and use openapi v3 support in a brand new v3 branch? #95

[Copilot]

Pull request overview

This PR adds new OpenAPI document generation capabilities using the oastools library, introducing BuildOAS2 and BuildOAS3 functions that complement the existing BuildSwagger API. The changes support OpenAPI versions from 2.0 through 3.2.0, with configurable schema naming strategies, generic type handling, and semantic deduplication.

Key changes:

• Introduces new BuildOAS2 and BuildOAS3 functions for generating OpenAPI specifications using the oastools library
• Adds comprehensive configuration options for schema naming strategies, generic type formatting, and semantic deduplication
• Modernizes development tooling with updated .golangci.yml (v2 format) and enhanced Makefile

Reviewed changes

Copilot reviewed 18 out of 20 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
oastools_types.go	Defines type aliases and constants for OAS versions and naming strategies
oastools_schema.go	Provides legacy tag support functions (reserved for future dual-tag integration)
oastools_builder.go	Core implementation of BuildOAS2 and BuildOAS3 functions
oastools_builder_test.go	Comprehensive test coverage for new OAS builder functions
config.go	Extends Config struct with oastools-specific configuration options
go.mod / go.sum	Updates dependencies including new oastools library
README.md	Comprehensive documentation update with examples and migration guide
.golangci.yml	Updates to v2 format with refined linter configuration
Makefile	Enhanced with additional targets and improved structure
utils_test.go	Improves error handling by explicitly ignoring return values
spec_resource.go	Fixes spelling error and adds error handling
spec_resource_test.go	Simplifies conditional logic
property_ext_test.go	Removes unused variables in tests
definition_builder.go	Changes return type and improves code quality
definition_builder_test.go	Updates property access and adds linter directives
lookup.go	Simplifies switch statement with default case
build_path_test.go	Fixes spelling and improves test assertions
examples/security/api.go	Updates struct initialization for go-openapi/spec compatibility
.gitignore	Adds IDE and Claude Code file exclusions

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[emicklei]

@erraggy thank you for contributing. I will review this addition.

[emicklei]

Shouldn't the NewOpenAPIService function check the config to decide which Build* function to call? I will try something

[erraggy]

Shouldn't the NewOpenAPIService function check the config to decide which Build* function to call? I will try something

You've found a gap I left behind in my implementation. I'll have a commit to address this shortly. Thank you.

[erraggy]

@emicklei I've addressed it in commit 4be62f0.

NewOpenAPIService now checks config.OASVersion to dispatch to the appropriate builder:

OASVersion Value	Builder Used	Output
>= OASVersion300	BuildOAS3	OAS 3.x document
== OASVersion20	BuildOAS2	OAS 2.0 via oastools
unset (zero)	BuildSwagger	OAS 2.0 via go-openapi/spec (legacy)

This maintains full backward compatibility — existing users who don't set OASVersion will continue using the legacy BuildSwagger path unchanged.

I also refactored to use a single any-typed document variable with an inline handler, which keeps the code DRY and eliminates the need for separate resource types.

Added tests for both new paths; coverage is back to baseline.

[erraggy]

That led me to dig deeper and look for any other gaps or issues, and I found a bunch. LOL. Another commit is incoming once I get all tests completed. 😄

[erraggy]

After a secondary thorough review, I've addressed all findings with 7be5e66:

Error Handling:

• NewOpenAPIService now returns HTTP 500 with error details instead of an empty WebService on build failure
• WriteAsJson errors are now logged instead of discarded
• BuildOAS3 returns an explicit error when called with OASVersion20

Feature Parity with Legacy Builder:

• Added AllowMultiple support (array params, collection format, min/max items, unique items)
• Added AllowEmptyValue for query/form parameters
• mapDefaultResponse now handles headers and extensions (consistent with mapResponse)

Code Quality:

• Deep-copy Extra map in shallowCopySchema to prevent shared mutation
• Added Config.Validate() for early misconfiguration detection
• Unknown data types now log a warning before defaulting to string

Tests:

• Added 8 new test functions covering error paths, header/form params, default responses, config validation, and all data type cases
• Coverage improved from 72.0% → 72.7%

Note: DataFormat for parameters isn't directly settable via oastools (format is inferred from Go type). For explicit format control, use PostBuildOAS2Handler/PostBuildOAS3Handler.

[erraggy]

Wow! Thanks for merging this, @emicklei.

I don't know how I didn't realize you had already merged this PR, but I kept right on going. LOL... 😂

I have a new release for oastools that addresses all remaining gaps to have full support:

• oastools v1.33.0

I can submit a follow-up PR to incorporate the added support if you'd like.