Can't generate description for object type in its definition.
Terminator637 opened this issue · comments
Describe the bug
Can't generate description for object type in its definition.
To Reproduce
Trying to add comments/annotations everywhere for my Errors struct but can't achieve expected behavior.
// Contextual errors map
type Errors struct {
DataLayerName string `json:"dataLayerName,omitempty" example:"can't be empty"`
}
type ErrorsResponse struct {
// Contextual errors map
Errors *Errors `json:"errors,omitempty"`
// List of important notifications
Notification []string `json:"notification,omitempty" example:"some important notification, other important notification"`
}Expected behavior
"handlers.Errors": {
"type": "object",
"description": "Contextual errors map",
"properties": {
"dataLayerName": {
"type": "string",
"example": "can't be empty"
},Visually it will look like on screenshot in Swagger UI Models if "description" will be there(added it manually):
Actual behavior
But got it without "description": "Contextual errors map":
"handlers.Errors": {
"type": "object",
"properties": {
"dataLayerName": {
"type": "string",
"example": "can't be empty"
},And in Swagger UI there is no description like on screenshot above.
Your swag version
latest master v1.6.6-0.20200519063744-e07798f56b23
Your go version
1.12.17
Desktop:
- OS: Ubuntu
- Version: 18.04
Parsed by go parser, struct has only one line of comment as shown below, and now swag has not use that comment line as default description.
//here is in global scope
type Name struct {
} //here is the comment in struct's scope.
Parsed by go parser, struct has only one line of comment as shown below, and now swag has not use that comment line as default description.
//here is in global scope type Name struct { } //here is the comment in struct's scope.
Sorry, tried comments as
// Contextual errors map
type Errors struct {
DataLayerName string `json:"dataLayerName,omitempty" example:"can't be empty"`
} // Contextual errors map
Nothing happens, the result is the same - there is no description in swagger file.
In fact, it is, but in the wrong place:
"handlers.CommonResponse": {
"type": "object",
"properties": {
"errors": {
"description": "Contextual errors map",
"type": "object",
"$ref": "#/definitions/handlers.Errors"
},But it must be in:
"handlers.Errors": {
"type": "object",
"description": "Contextual errors map",
"properties": {
"dataLayerName": {
"type": "string",
"example": "can't be empty"
},If i add description manually here, then swagger UI shows me this description as on the screenshot above.
Description is bind to field, not a struct.
If you use it as
type ErrorsResponse struct {
// Contextual errors map
Errors *Errors `json:"errors,omitempty"`
// List of important notifications
Notification []string `json:"notification,omitempty" example:"some important notification, other important notification"`
}
,
you will see description Contextual errors map for field Errors in definition of ErrorsResponse.
If
type Errors struct {
// Contextual errors map
DataLayerName string `json:"dataLayerName,omitempty" example:"can't be empty"`
}
,
you will see description Contextual errors map for field DataLayerName in definition of Errors.
If
// Contextual errors map
type Errors struct {
DataLayerName string `json:"dataLayerName,omitempty" example:"can't be empty"`
}
,
You can't see it.
I'm offer next solution of this problem in code:
patch.zip (file inside archive can be applyed by command git apply)
@KuboOrk Thanks for figuring it out. Unfortunately, this is not the way we are accepting code contributions.
Can I solve this task and contribute it the right way?