github.com/kaisawind/go-swagger@v0.19.0/docs/use/spec/response.md (about)

     1  # swagger:response
     2  
     3  Reads a struct decorated with **swagger:response** and uses that information to fill up the headers and the schema for a response.
     4  A swagger:route can specify a response name for a status code and then the matching response will be used for that operation in the swagger definition.
     5  
     6  <!--more-->
     7  
     8  ##### Syntax:
     9  
    10  ```
    11  swagger:response [?response name]
    12  ```
    13  
    14  ##### Properties:
    15  
    16  Annotation | Description
    17  -----------|------------
    18  **In** | where to find the field
    19  **Collection Format** | when a slice the formatter for the collection when serialized on the request
    20  **Maximum** | specifies the maximum a number or integer value can have
    21  **Minimum** | specifies the minimum a number or integer value can have
    22  **Multiple of** | specifies a value a number or integer value must be a multiple of
    23  **Minimum length** | the minimum length for a string value
    24  **Maximum length** | the maximum length for a string value
    25  **Pattern** | a regular expression a string value needs to match
    26  **Minimum items** | the minimum number of items a slice needs to have
    27  **Maximum items** | the maximum number of items a slice can have
    28  **Unique** | when set to true the slice can only contain unique items
    29  **Example** | an example value, parsed as the field's type<br/>(objects and slices are parsed as JSON)
    30  
    31  For slice properties there are also items to be defined. This might be a nested collection, for indicating nesting
    32  level the value is a 0-based index, so items.minLength is the same as items.0.minLength
    33  
    34  Annotation | Format
    35  -----------|--------
    36  **Items.*n*.Maximum** |  specifies the maximum a number or integer value can have at the level *n*
    37  **Items.*n*.Minimum** |  specifies the minimum a number or integer value can have at the level *n*
    38  **Items.*n*.Multiple of** | specifies a value a number or integer value must be a multiple of
    39  **Items.*n*.Minimum length** | the minimum length for a string value at the level *n*
    40  **Items.*n*.Maximum length** | the maximum length for a string value at the level *n*
    41  **Items.*n*.Pattern** | a regular expression a string value needs to match at the level *n*
    42  **Items.*n*.Minimum items** | the minimum number of items a slice needs to have at the level *n*
    43  **Items.*n*.Maximum items** | the maximum number of items a slice can have at the level *n*
    44  **Items.*n*.Unique** | when set to true the slice can only contain unique items at the level *n*
    45  
    46  ##### Example:
    47  
    48  ```go
    49  // A ValidationError is an error that is used when the required input fails validation.
    50  // swagger:response validationError
    51  type ValidationError struct {
    52  	// The error message
    53  	// in: body
    54  	Body struct {
    55  		// The validation message
    56  		//
    57  		// Required: true
    58  		// Example: Expected type int
    59  		Message string
    60  		// An optional field name to which this validation applies
    61  		FieldName string
    62  	}
    63  }
    64  ```
    65  
    66  ##### Result:
    67  
    68  ```yaml
    69  ---
    70  responses:
    71    validationError:
    72      description: A ValidationError is an error that is used when the required input fails validation.
    73      schema:
    74        type: object
    75        description: The error message
    76        required:
    77        - Message
    78        properties:
    79          Message:
    80            type: string
    81            description: The validation message
    82            example: Expected type int
    83          FieldName:
    84            type: string
    85            description: an optional field name to which this validation applies
    86  ```