github.com/go-swagger/go-swagger@v0.31.0/docs/reference/annotations/operation.md (about)

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