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

Introduce a new command-line parameter for "generate spec" allowing to set "x-nullable: true" by default for each Go field having a pointer type and not having JSON 'omitempty' option set #3128

Open
wants to merge 4 commits into
base: master
Choose a base branch
from

Conversation

zenovich
Copy link

@zenovich zenovich commented Aug 12, 2024

With this new feature, we can skip unnecessary annotations for pointer-type fields as they are almost always nullable. So instead of

// swagger:model Item
type Item struct {
	// Extensions:
	// ---
	// x-nullable: true
	Value *int64 `json:"value"`
}

we can simply write

// swagger:model Item
type Item struct {
	Value *int64 `json:"value"`
}

with the same effect when running

swagger generate spec --scan-models --nullable-pointers -o ./swagger.yaml && swagger validate ./swagger.yaml

instead of usual

swagger generate spec --scan-models -o ./swagger.yaml && swagger validate ./swagger.yaml

Although rarely needed, it is still possible to mark a field as non-nullable explicitly:

// swagger:model Item
type Item struct {
	// Extensions:
	// ---
	// x-nullable: false
	Value *int64 `json:"value"`
}

Also, x-nullable: true will not be set automatically for fields having the JSON 'omitempty' option set:

// swagger:model Item
type Item struct {
	Value *int64 `json:"value,omitempty"`
}

It works even for fields pointing to embedded structures.

Then, it's possible to convert the generated spec to OpenAPI 3.0 preserving the x-nullable tags and converting them to nullable tags:

swagger2openapi --refSiblings allOf --yaml swagger.yaml | sed 's/x-nullable:/nullable:/g' > openapi3.yaml

and preview the documentation:

redocly preview-docs openapi3.yaml

and build the documentation:

redocly build-docs openapi3.yaml

The field in the documentation will look as
Screenshot 2024-08-12 at 17 33 33

…o set "x-nullable: true" by default for each Go field having a pointer type and not having JSON 'omitempty' option set

Signed-off-by: Dmitry Zenovich <dzenovich@gmail.com>
@zenovich zenovich force-pushed the pointers_nullable_by_default branch from 567e2ee to 20fa9d7 Compare August 14, 2024 13:30
@zenovich zenovich changed the title Introduce a new command-line parameter for "generate spec" allowing to set "x-nullable: true" by default for each Go field having a pointer type Introduce a new command-line parameter for "generate spec" allowing to set "x-nullable: true" by default for each Go field having a pointer type and not having JSON 'omitempty' option set Aug 14, 2024
Copy link

codecov bot commented Sep 23, 2024

Codecov Report

Attention: Patch coverage is 0% with 31 lines in your changes missing coverage. Please review.

Project coverage is 32.35%. Comparing base (d16f7fe) to head (00e1aca).

Files with missing lines Patch % Lines
codescan/schema.go 0.00% 16 Missing ⚠️
codescan/application.go 0.00% 12 Missing ⚠️
cmd/swagger/commands/generate/spec.go 0.00% 1 Missing ⚠️
codescan/parameters.go 0.00% 1 Missing ⚠️
codescan/responses.go 0.00% 1 Missing ⚠️
Additional details and impacted files
@@           Coverage Diff           @@
##           master    #3128   +/-   ##
=======================================
  Coverage   32.35%   32.35%           
=======================================
  Files          61       61           
  Lines       12862    12862           
=======================================
  Hits         4161     4161           
  Misses       8361     8361           
  Partials      340      340           
Flag Coverage Δ
codegen-oldstable-canary-fixtures 32.35% <0.00%> (ø)
codegen-stable-canary-fixtures 32.35% <0.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

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