Skip to content
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.

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

feat: set a description to the schema request body #100

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

chuliang
Copy link

Allow to set a description to a schema used as request body

Example:
Input struct:

type RouteInput struct {
    _ struct{} `json:"-" description:"Description of the input schema"`
    FieldA string `json:"field_a" description:"field_a description"`
    ...
}

Generated schema:

{
	"RouteInput": {
		"type": "object",
		"properties": {
			"field_a": {
				"type": "string",
				"description": "field_a description"
			},
			...
		},
		"description": "Description of the input schema",
	}
}

@wI2L
Copy link
Owner

wI2L commented Mar 28, 2023

@chuliang

Hello,

Regarding the feature itself, I'm not against it, but the implementation itself isn't what I would recommend. Instead of having to rely on unexported struct fields, we could instead provide a package function to register a description for each type (in a global map protected with a mutex). This could then in turn be used by the generator to generate the "components/schemas" part of the spec.

See newSchemaFromType.

So, in terms of usage, this would give something like this:

type RouteInput struct {
    FieldA string `json:"field_a" description:"field_a description"`
}

func init() {
  fizz.RegisterSchemaDescription(RouteInput{}, "Description of the input schema")
}

wdyt ?

@chuliang chuliang force-pushed the feat/schema-description branch 2 times, most recently from c0af0c7 to a9e39a8 Compare April 13, 2023 10:12
@chuliang
Copy link
Author

Hello @wI2L :)
Thanks for your review.

I think fizz.RegisterSchemaDescription(...) remove the benefit of Tonic to register input schema from the route function parameter.
I updated my PR with another way to provide a description for the RequestBody schema.
Is it better for you?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants