github.com/AngusLu/go-swagger@v0.28.0/docs/use/spec/operation.md (about)

     1  # swagger:operation
     2  
     3  A **swagger:operation** annotation links a path to a method.
     4  This operation gets a unique id, which is used in various places as method name.
     5  One such usage is in method names for client generation for example.
     6  
     7  Because there are many routers available, this tool does not try to parse the paths
     8  you provided to your routing library of choice. So you have to specify your path pattern
     9  yourself in valid swagger (YAML) syntax.
    10  
    11  <!--more-->
    12  
    13  ##### Syntax:
    14  
    15  ```
    16  swagger:operation [method] [path pattern] [?tag1 tag2 tag3] [operation id]
    17  ```
    18  
    19  ##### Properties:
    20  
    21  Any valid Swagger 2.0 YAML _Operation_ property is valid.
    22  Make sure your indentation is consistent and correct,
    23  as it won't parse correctly otherwise.
    24  
    25  You can find all the properties at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operationObject
    26  
    27  Note that if you specify the _tags_, _summary_, _description_ or _operationId_ as part of the
    28  YAML spec, you will override the _summary_, _descriptions_, _tags_ or _operationId_, specified as part of the regular swagger syntax above.
    29  
    30  Also note that you need to start your YAML spec with a triple dash `---`.
    31  
    32  ##### Example:
    33  
    34  ```go
    35  // ServeAPI serves the API for this record store
    36  func ServeAPI(host, basePath string, schemes []string) (err error) {
    37  	// swagger:operation GET /pets getPet
    38  	//
    39  	// Returns all pets from the system that the user has access to
    40  	//
    41  	// Could be any pet
    42  	//
    43  	// ---
    44  	// produces:
    45  	// - application/json
    46  	// - application/xml
    47  	// - text/xml
    48  	// - text/html
    49  	// parameters:
    50  	// - name: tags
    51  	//   in: query
    52  	//   description: tags to filter by
    53  	//   required: false
    54  	//   type: array
    55  	//   items:
    56  	//     type: string
    57  	//   collectionFormat: csv
    58  	// - name: limit
    59  	//   in: query
    60  	//   description: maximum number of results to return
    61  	//   required: false
    62  	//   type: integer
    63  	//   format: int32
    64  	// responses:
    65  	//   '200':
    66  	//     description: pet response
    67  	//     schema:
    68  	//       type: array
    69  	//       items:
    70  	//         "$ref": "#/definitions/pet"
    71  	//   default:
    72  	//     description: unexpected error
    73  	//     schema:
    74  	//       "$ref": "#/definitions/errorModel"
    75  	mountItem("GET", basePath+"/pets", nil)
    76  
    77      return
    78  }
    79  ```
    80  
    81  ##### Result:
    82  
    83  ```yaml
    84  ---
    85  paths:
    86    "/pets":
    87      get:
    88        summary: Returns all pets from the system that the user has access to
    89        description: Could be any pet
    90        produces:
    91          - application/json
    92          - application/xml
    93          - text/xml
    94          - text/html
    95        operationId: getPet
    96        parameters:
    97          - type: array
    98            items:
    99              type: string
   100            collectionFormat: csv
   101            description: tags to filter by
   102            name: tags
   103            in: query
   104          - type: integer
   105            format: int32
   106            description: maximum number of results to return
   107            name: limit
   108            in: query
   109        responses:
   110          '200':
   111            description: pet response
   112            schema:
   113              type: array
   114              items:
   115                $ref: "#/definitions/pet"
   116          default:
   117            description: unexpected error
   118            schema:
   119              $ref: "#/definitions/errorModel"
   120  ```