Merge pull request #2 from oaswrap/refactor/change-openapi-library

refactor: change openapi library

Author: akfaiz

ARCHITECTURE.md

@@ -103,7 +103,7 @@ Key global stacks (all touched only during tree construction — effectively sin
 
 ### Phase 3 — Output
 
-`WriteSpec()` locks the `SpecCollector`, serialises the `openapi3.Spec` to YAML or JSON, and writes the file.
+`WriteSpec()` locks the `SpecCollector`, serialises the `openapi.Document` to YAML or JSON, and writes the file.
 
 ---
 
@@ -144,19 +144,20 @@ dslRespExec
 
 ### `SpecCollector` (`spec.go`, `spec_collector.go`)
 
-Thread-safe accumulator wrapping the `openapi3.Reflector`.
+Thread-safe accumulator wrapping a persistent `oaswrap/spec/openapi.Document`.
 
 ```
 SpecCollector          (struct declared in spec.go)
 ├── mu sync.Mutex          ← protects all spec mutations
-├── reflector              ← swaggest/openapi-go reflector
+├── doc                    ← generated OpenAPI document
+├── openapiOpts            ← oaswrap/spec generator options
 └── excludePaths []string
 ```
 
 `newSpecCollector` (in `spec_collector.go`) is decomposed into:
-- `applySchemaOptions` — wires JSON-schema reflector options (generic name shortening, inline refs, type maps)
+- `buildOpenAPIOptions` — wires root metadata, security schemes, and reflector options for `oaswrap/spec`
 - `shortenGenericName` — strips package paths from generic type-argument names
-- `applySpecInfo` → `applySpecTags` / `applySpecServers` — populates the OpenAPI Info/Tags/Servers blocks
+- per-operation registration reflects through a temporary `spec.Router`, then merges the generated document into the collector
 
 Four lock points: `Register`, `RegisterDSLOperation`, `injectRecordedResponseSchema`, `appendExamplesLocked`.
 
@@ -226,15 +227,15 @@ See `examples/parallel` for a working end-to-end example using schema inference
 ### DSL path (recommended)
 
 1. `Path` / `Get` / `Response` / `RequestBody` / `ResponseSchema` declare metadata during tree construction.
-2. `flushPendingDSLOps` (first `RunTest`) calls `RegisterDSLOperation` which drives the `openapi3.Reflector` directly.
-3. `injectInferredRequestSchema` is **skipped** if the reflector already placed a schema for any content-type key in `requestBody.content` — preventing conflict when `Consumes` and `SetRawBody` use different content-type strings.
+2. `flushPendingDSLOps` (first `RunTest`) calls `RegisterDSLOperation`, which reflects a temporary `oaswrap/spec` route and merges the generated operation into the collector document.
+3. `injectInferredRequestSchema` is **skipped** if registration already placed a schema for any content-type key in `requestBody.content` — preventing conflict when `Consumes` and `SetRawBody` use different content-type strings.
 
 ### Runtime-only path (no DSL)
 
 For tests that use `requestBuilder` directly (or through the legacy `Register` codepath):
 
 1. `Register` is called with the builder and recorded response.
-2. `AddReqStructure` / `AddRespStructure` drive the reflector from the builder's typed fields.
+2. `option.Request` / `option.Response` drive `oaswrap/spec` reflection from the builder's typed fields.
 3. `injectInferredRequestSchema` fills any gaps from actual request bytes.
 4. `injectInferredSchema` fills response schema from actual response bytes when none was declared.
 

README.md

@@ -6,7 +6,7 @@
 [![codecov](https://codecov.io/gh/oaswrap/gswag/graph/badge.svg?token=X8zEVtNy5e)](https://codecov.io/gh/oaswrap/gswag)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Generate OpenAPI 3.0 specs directly from your [Ginkgo](https://github.com/onsi/ginkgo) integration tests.
+Generate OpenAPI 3.0, 3.1, or 3.2 specs directly from your [Ginkgo](https://github.com/onsi/ginkgo) integration tests.
 
 Inspired by [rswag](https://github.com/rswag/rswag): define API docs alongside executable tests using a nested DSL.
 
@@ -246,6 +246,7 @@ Get("Get order", func() {
 Init(&Config{
     Title:           "My API",           // required
     Version:         "1.0.0",            // required
+    OpenAPIVersion:  OpenAPI310,         // default: 3.1.2
     Description:     "Public API",
     TermsOfService:  "https://example.com/terms",
     Contact: &ContactConfig{
@@ -306,6 +307,12 @@ Security helpers:
 - `APIKeyCookie(name)`
 - `OAuth2Implicit(authURL, scopes)`
 
+OpenAPI version constants:
+
+- `OpenAPI300`, `OpenAPI301`, `OpenAPI302`, `OpenAPI303`, `OpenAPI304`
+- `OpenAPI310`, `OpenAPI311`, `OpenAPI312`
+- `OpenAPI320`
+
 ## Gomega Matchers
 
 Matchers operate on `*http.Response` (the object passed to `RunTest` callback):

builder_test.go

@@ -89,7 +89,7 @@ func TestRequestBuilder_Do_SuccessRegisters(t *testing.T) {
 	}
 
 	// spec should have registered path
-	if _, ok := sc.reflector.Spec.Paths.MapOfPathItemValues["/test"]; !ok {
+	if _, ok := sc.doc.Paths["/test"]; !ok {
 		t.Fatalf("expected spec to contain /test")
 	}
 }

config.go

@@ -13,6 +13,19 @@ const (
 	JSON
 )
 
+// OpenAPI version constants.
+const (
+	OpenAPI300 = "3.0.0"
+	OpenAPI301 = "3.0.1"
+	OpenAPI302 = "3.0.2"
+	OpenAPI303 = "3.0.3"
+	OpenAPI304 = "3.0.4"
+	OpenAPI310 = "3.1.0"
+	OpenAPI311 = "3.1.1"
+	OpenAPI312 = "3.1.2"
+	OpenAPI320 = "3.2.0"
+)
+
 // ServerConfig describes an OpenAPI server entry.
 type ServerConfig struct {
 	URL         string
@@ -65,35 +78,43 @@ type SecuritySchemeConfig struct {
 	Scopes           map[string]string // scope -> description
 }
 
+// Security scheme type constants.
+const (
+	SecurityTypeHTTP   = "http"
+	SecurityTypeAPIKey = "apiKey"
+	SecurityTypeOAuth2 = "oauth2"
+)
+
 // BearerJWT returns a SecuritySchemeConfig for an HTTP Bearer JWT scheme.
 func BearerJWT() SecuritySchemeConfig {
-	return SecuritySchemeConfig{Type: "http", Scheme: "bearer", BearerFormat: "JWT"}
+	return SecuritySchemeConfig{Type: SecurityTypeHTTP, Scheme: "bearer", BearerFormat: "JWT"}
 }
 
 // APIKeyHeader returns a SecuritySchemeConfig for an API key passed in a header.
 func APIKeyHeader(headerName string) SecuritySchemeConfig {
-	return SecuritySchemeConfig{Type: "apiKey", In: "header", Name: headerName}
+	return SecuritySchemeConfig{Type: SecurityTypeAPIKey, In: "header", Name: headerName}
 }
 
 // APIKeyQuery returns a SecuritySchemeConfig for an API key passed in a query param.
 func APIKeyQuery(paramName string) SecuritySchemeConfig {
-	return SecuritySchemeConfig{Type: "apiKey", In: "query", Name: paramName}
+	return SecuritySchemeConfig{Type: SecurityTypeAPIKey, In: "query", Name: paramName}
 }
 
 // APIKeyCookie returns a SecuritySchemeConfig for an API key passed in a cookie.
 func APIKeyCookie(cookieName string) SecuritySchemeConfig {
-	return SecuritySchemeConfig{Type: "apiKey", In: "cookie", Name: cookieName}
+	return SecuritySchemeConfig{Type: SecurityTypeAPIKey, In: "cookie", Name: cookieName}
 }
 
 // OAuth2Implicit returns a SecuritySchemeConfig for an OAuth2 implicit flow.
 func OAuth2Implicit(authURL string, scopes map[string]string) SecuritySchemeConfig {
-	return SecuritySchemeConfig{Type: "oauth2", AuthorizationURL: authURL, Scopes: scopes}
+	return SecuritySchemeConfig{Type: SecurityTypeOAuth2, AuthorizationURL: authURL, Scopes: scopes}
 }
 
 // Config holds global settings for gswag.
 type Config struct {
 	Title          string
 	Version        string
+	OpenAPIVersion string // default: "3.1.2"
 	Description    string
 	TermsOfService string
 	Contact        *ContactConfig
@@ -153,6 +174,9 @@ func Init(cfg *Config) {
 	if cfg.Version == "" {
 		cfg.Version = "0.1.0"
 	}
+	if cfg.OpenAPIVersion == "" {
+		cfg.OpenAPIVersion = OpenAPI312
+	}
 	globalConfig = cfg
 	globalCollector = newSpecCollector(cfg)
 	// Reset the flush gate so re-initialisation (e.g. across test suites in the

dsl_test.go

@@ -91,7 +91,7 @@ func TestFlushPendingDSLOpsRegisters(t *testing.T) {
 	flushPendingDSLOps()
 
 	// check spec has path
-	if _, ok := sc.reflector.Spec.Paths.MapOfPathItemValues["/x"]; !ok {
+	if _, ok := sc.doc.Paths["/x"]; !ok {
 		t.Fatalf("expected pending op to be registered into spec")
 	}
 

examples/chi/docs/openapi.yaml

@@ -1,128 +1,135 @@
-openapi: 3.0.3
+openapi: 3.1.2
 info:
   title: Orders API (Chi)
   version: 1.0.0
 paths:
   /orders:
     get:
+      tags:
+        - orders
+      summary: List all orders
+      description: List all orders
       parameters:
-      - in: query
-        name: status
-        schema:
-          type: string
-      - in: query
-        name: limit
-        schema:
-          type: integer
+        - name: status
+          in: query
+          schema:
+            type: string
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            format: int32
       responses:
-        "200":
+        '200':
+          description: list of orders
           content:
             application/json:
               schema:
+                type: array
                 items:
                   $ref: '#/components/schemas/ApiOrder'
-                type: array
-          description: OK
       security:
-      - apiKey: []
-      summary: List all orders
-      tags:
-      - orders
+        - apiKey: []
     post:
+      tags:
+        - orders
+      summary: Place an order
+      description: Place an order
       requestBody:
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/ApiCreateOrderRequest'
       responses:
-        "201":
+        '201':
+          description: order placed
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ApiOrder'
-          description: Created
-        "400":
+        '400':
+          description: bad request
           content:
             application/json:
               schema:
+                type: object
                 properties:
                   error:
                     type: string
-                type: object
-          description: Bad Request
       security:
-      - apiKey: []
-      summary: Place an order
-      tags:
-      - orders
+        - apiKey: []
   /orders/{id}:
-    delete:
-      deprecated: true
-      parameters:
-      - in: path
-        name: id
-        required: true
-        schema:
-          type: string
-      responses:
-        "204":
-          description: No Content
-      security:
-      - apiKey: []
-      summary: Cancel an order
-      tags:
-      - orders
     get:
+      tags:
+        - orders
+      summary: Get order by ID
+      description: Get order by ID
       parameters:
-      - in: path
-        name: id
-        required: true
-        schema:
-          type: string
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
       responses:
-        "200":
+        '200':
+          description: order found
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ApiOrder'
-          description: OK
-        "404":
+        '404':
+          description: order not found
           content:
             application/json:
               schema:
+                type: object
                 properties:
                   error:
                     type: string
-                type: object
-          description: Not Found
       security:
-      - apiKey: []
-      summary: Get order by ID
+        - apiKey: []
+    delete:
       tags:
-      - orders
+        - orders
+      summary: Cancel an order
+      description: Cancel an order
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '204':
+          description: order cancelled
+      deprecated: true
+      security:
+        - apiKey: []
 components:
   schemas:
     ApiCreateOrderRequest:
+      type: object
       properties:
         product:
           type: string
         quantity:
           type: integer
-      type: object
+          format: int32
     ApiOrder:
+      type: object
       properties:
         id:
           type: string
         product:
           type: string
         quantity:
           type: integer
+          format: int32
         total:
-          format: double
           type: number
-      type: object
+          format: double
   securitySchemes:
     apiKey:
-      in: header
-      name: X-API-Key
       type: apiKey
+      name: X-API-Key
+      in: header

examples/chi/go.mod

@@ -14,11 +14,10 @@ require (
 	github.com/Masterminds/semver/v3 v3.4.0 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
+	github.com/goccy/go-yaml v1.19.2 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83 // indirect
-	github.com/swaggest/jsonschema-go v0.3.79 // indirect
-	github.com/swaggest/openapi-go v0.2.60 // indirect
-	github.com/swaggest/refl v1.4.0 // indirect
+	github.com/oaswrap/spec v0.5.0 // indirect
 	github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f // indirect
 	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
 	github.com/xeipuuv/gojsonschema v1.2.0 // indirect
@@ -29,7 +28,6 @@ require (
 	golang.org/x/sys v0.40.0 // indirect
 	golang.org/x/text v0.33.0 // indirect
 	golang.org/x/tools v0.41.0 // indirect
-	gopkg.in/yaml.v2 v2.4.0 // indirect
 )
 
 replace github.com/oaswrap/gswag => ../../