Skip to content

Can't generate description for object type in its definition. #708

Open

Description

@Terminator637

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):
2020-05-22_21-09

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

Activity

  1. sdghchj commented on May 23, 2020

    @sdghchj
    Member

    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.
    
  2. Terminator637 commented on May 23, 2020

    @Terminator637
    Author

    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.

  3. Terminator637 commented on May 23, 2020

    @Terminator637
    Author

    @sdghchj, as I understand, it's not implemented now, right?

  4. sdghchj commented on May 23, 2020

    @sdghchj
    Member

    @sdghchj, as I understand, it's not implemented now, right?

    Yes

  5. sdghchj commented on May 29, 2020

    @sdghchj
    Member

    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.

  6. KuboOrk commented on Jan 18, 2022

    @KuboOrk
    Contributor

    I'm offer next solution of this problem in code:
    patch.zip (file inside archive can be applyed by command git apply)

  7. ubogdan commented on Jan 18, 2022

    @ubogdan
    Contributor

    @KuboOrk Thanks for figuring it out. Unfortunately, this is not the way we are accepting code contributions.

  8. KuboOrk commented on Jan 19, 2022

    @KuboOrk
    Contributor

    Can I solve this task and contribute it the right way?

  9. ubogdan commented on Jan 19, 2022

    @ubogdan
    Contributor

    @KuboOrk This is an Open Source project. All the contributions are welcome.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      ⌂ 换网址