Skip to content

feat: adjust reflection #62

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
akfaiz merged 6 commits into from
May 11, 2026
Merged

feat: adjust reflection #62

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
30a5d80
feat: add InterceptSchema/InterceptProp hooks, fix uint formats, patc…
akfaiz May 11, 2026
9347a9b
docs: update README for uint format fix and new reflector hooks
akfaiz May 11, 2026
c117263
chore: update example openapi
akfaiz May 11, 2026
36dfcb6
fix: fix issue at lint and marshal yaml to read yaml tag
akfaiz May 11, 2026
6df6e6a
feat: fix InterceptSchema/InterceptProp hook correctness and error pr…
akfaiz May 11, 2026
c2d86f9
test: increase code coverage of this project
akfaiz May 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 21 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,9 @@ Code-first, framework-agnostic OpenAPI 3.x spec builder for Go. Generate docs fr
- Low-level typed OpenAPI model for direct field control.
- `spec.OneOf` for explicit one-of schemas.
- `SchemaExposer` and `StaticSchemaExposer` hooks for custom reflected schemas.
- `InterceptSchema` hook for type-level schema customization and override.
- `InterceptProp` hook for field-level property filtering and modification.
- `RequiredPropByValidateTag` option to derive `required` from `validate` struct tags.

---

Expand Down Expand Up @@ -424,8 +427,8 @@ type SearchRequest struct {
| `bool` | `type: boolean` |
| Signed integers (except `int64`) | `type: integer`, `format: int32` |
| `int64` | `type: integer`, `format: int64` |
| Unsigned integers (except `uint64`/`uintptr`) | `type: integer`, `format: int32`, `minimum: 0` |
| `uint64`, `uintptr` | `type: integer`, `format: int64`, `minimum: 0` |
| `uint8`, `uint16` | `type: integer`, `format: int32`, `minimum: 0` |
| `uint`, `uint32`, `uint64`, `uintptr` | `type: integer`, `format: int64`, `minimum: 0` |
| `float32` | `type: number`, `format: float` |
| `float64` | `type: number`, `format: double` |
| `string` | `type: string` |
Expand Down Expand Up @@ -466,6 +469,19 @@ r := spec.NewRouter(
option.InterceptDefName(func(t reflect.Type, defaultName string) string {
return defaultName
}),
option.InterceptSchema(func(params openapi.InterceptSchemaParams) (stop bool, err error) {
if params.Processed {
params.Schema.Extensions = map[string]any{"x-go-type": params.Type.String()}
}
return false, nil
}),
option.InterceptProp(func(params openapi.InterceptPropParams) error {
if params.Processed && params.Field.Tag.Get("internal") == "true" {
return openapi.ErrSkipProperty
}
return nil
}),
option.RequiredPropByValidateTag(), // marks fields required when validate tag contains "required"
),
)
```
Expand All @@ -477,6 +493,9 @@ r := spec.NewRouter(
| `TypeMapping(src, dst)` | Reflect `src` as if it were `dst`. |
| `ParameterTagMapping(in, sourceTag)` | Add a custom tag for a parameter location while keeping the default tag. |
| `InterceptDefName(fn)` | Customize schema component names. |
| `InterceptSchema(fn)` | Hook called before and after each type is reflected. Pre-call (`Processed=false`): return `stop=true` to override schema entirely. Post-call (`Processed=true`): modify the built schema. |
| `InterceptProp(fn)` | Hook called before and after each struct field is reflected. Return `openapi.ErrSkipProperty` to exclude the field. |
| `RequiredPropByValidateTag(tag, sep...)` | Mark properties as required when their `validate` tag (or custom tag) contains `"required"`. Default tag: `validate`, default separator: `,`. |

---

Expand Down
12 changes: 6 additions & 6 deletions examples/basic/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
openapi: 3.0.4
openapi: 3.1.2
info:
title: My API
version: 1.0.0
Expand All @@ -13,14 +13,14 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/LoginRequest"
$ref: '#/components/schemas/LoginRequest'
responses:
"200":
'200':
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/LoginResponse"
$ref: '#/components/schemas/LoginResponse'
/api/v1/users/{id}:
get:
summary: Get user by ID
Expand All @@ -32,12 +32,12 @@ paths:
schema:
type: string
responses:
"200":
'200':
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/User"
$ref: '#/components/schemas/User'
security:
- bearerAuth: []
components:
Expand Down
76 changes: 38 additions & 38 deletions examples/petstore/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
openapi: 3.0.3
openapi: 3.1.2
info:
title: Petstore API
description: This is a sample Petstore server.
Expand Down Expand Up @@ -39,14 +39,14 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
$ref: '#/components/schemas/Pet'
responses:
"200":
'200':
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
$ref: '#/components/schemas/Pet'
security:
- petstore_auth:
- write:pets
Expand All @@ -61,14 +61,14 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
$ref: '#/components/schemas/Pet'
responses:
"201":
'201':
description: Created
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
$ref: '#/components/schemas/Pet'
security:
- petstore_auth:
- write:pets
Expand All @@ -90,14 +90,14 @@ paths:
- pending
- sold
responses:
"200":
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Pet"
$ref: '#/components/schemas/Pet'
security:
- petstore_auth:
- write:pets
Expand All @@ -117,14 +117,14 @@ paths:
items:
type: string
responses:
"200":
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Pet"
$ref: '#/components/schemas/Pet'
security:
- petstore_auth:
- write:pets
Expand All @@ -144,12 +144,12 @@ paths:
type: integer
format: int32
responses:
"200":
'200':
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
$ref: '#/components/schemas/Pet'
security:
- petstore_auth:
- write:pets
Expand All @@ -169,7 +169,7 @@ paths:
type: integer
format: int32
responses:
"200":
'200':
description: OK
security:
- petstore_auth:
Expand All @@ -193,7 +193,7 @@ paths:
schema:
type: string
responses:
"204":
'204':
description: No Content
security:
- petstore_auth:
Expand All @@ -218,12 +218,12 @@ paths:
schema:
type: string
responses:
"200":
'200':
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
$ref: '#/components/schemas/ApiResponse'
security:
- petstore_auth:
- write:pets
Expand All @@ -236,7 +236,7 @@ paths:
description: Returns a map of status codes to quantities.
operationId: getInventory
responses:
"200":
'200':
description: OK
content:
application/json:
Expand All @@ -258,14 +258,14 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
$ref: '#/components/schemas/Order'
responses:
"201":
'201':
description: Created
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
$ref: '#/components/schemas/Order'
/store/order/{orderId}:
get:
tags:
Expand All @@ -281,13 +281,13 @@ paths:
type: integer
format: int32
responses:
"200":
'200':
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
"404":
$ref: '#/components/schemas/Order'
'404':
description: Not Found
delete:
tags:
Expand All @@ -303,7 +303,7 @@ paths:
type: integer
format: int32
responses:
"204":
'204':
description: No Content
/user:
post:
Expand All @@ -316,14 +316,14 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/User"
$ref: '#/components/schemas/User'
responses:
"201":
'201':
description: Created
content:
application/json:
schema:
$ref: "#/components/schemas/User"
$ref: '#/components/schemas/User'
/user/createWithList:
post:
tags:
Expand All @@ -337,9 +337,9 @@ paths:
schema:
type: array
items:
$ref: "#/components/schemas/User"
$ref: '#/components/schemas/User'
responses:
"201":
'201':
description: Created
/user/{username}:
get:
Expand All @@ -355,13 +355,13 @@ paths:
schema:
type: string
responses:
"200":
'200':
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/User"
"404":
$ref: '#/components/schemas/User'
'404':
description: Not Found
put:
tags:
Expand Down Expand Up @@ -404,13 +404,13 @@ paths:
username:
type: string
responses:
"200":
'200':
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/User"
"404":
$ref: '#/components/schemas/User'
'404':
description: Not Found
delete:
tags:
Expand All @@ -425,7 +425,7 @@ paths:
schema:
type: string
responses:
"204":
'204':
description: No Content
components:
schemas:
Expand Down Expand Up @@ -491,7 +491,7 @@ components:
tags:
type: array
items:
$ref: "#/components/schemas/Tag"
$ref: '#/components/schemas/Tag'
type:
type: string
Tag:
Expand Down
1 change: 0 additions & 1 deletion examples/petstore/router.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ import (

func createRouter() spec.Generator {
r := spec.NewRouter(
option.WithOpenAPIVersion("3.0.3"),
option.WithTitle("Petstore API"),
option.WithDescription("This is a sample Petstore server."),
option.WithVersion("1.0.0"),
Expand Down
Loading
Loading