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

     1  # swagger:route
     2  
     3  A **swagger:route** 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 syntax.
    10  
    11  <!--more-->
    12  
    13  ##### Syntax:
    14  
    15  ```
    16  swagger:route [method] [path pattern] [?tag1 tag2 tag3] [operation id]
    17  ```
    18  
    19  ##### Properties:
    20  
    21  Annotation | Format
    22  -----------|--------
    23  **Consumes** | a list of operation specific mime type values, one per line, for the content the API receives
    24  **Produces** | a list of operation specific mime type values, one per line, for the content the API sends
    25  **Schemes** | a list of operation specific schemes the API accept (possible values: http, https, ws, wss) https is preferred as default when configured
    26  **Security** | a dictionary of key: []string{scopes}
    27  **Responses** | a dictionary of status code to named response
    28  
    29  ##### Example:
    30  
    31  ```go
    32  // ServeAPI serves the API for this record store
    33  func ServeAPI(host, basePath string, schemes []string) error {
    34  
    35  	// swagger:route GET /pets pets users listPets
    36  	//
    37  	// Lists pets filtered by some parameters.
    38  	//
    39  	// This will show all available pets by default.
    40  	// You can get the pets that are out of stock
    41  	//
    42  	//     Consumes:
    43  	//     - application/json
    44  	//     - application/x-protobuf
    45  	//
    46  	//     Produces:
    47  	//     - application/json
    48  	//     - application/x-protobuf
    49  	//
    50  	//     Schemes: http, https, ws, wss
    51  	//
    52  	//     Security:
    53  	//       api_key:
    54  	//       oauth: read, write
    55  	//
    56  	//     Responses:
    57  	//       default: genericError
    58  	//       200: someResponse
    59  	//       422: validationError
    60  	mountItem("GET", basePath+"/pets", nil)
    61  }
    62  ```
    63  
    64  ##### Result:
    65  
    66  ```yaml
    67  ---
    68  paths:
    69    "/pets":
    70      get:
    71        operationId: listPets
    72        summary: Lists pets filtered by some parameters.
    73        description: "This will show all available pets by default.\nYou can get the pets that are out of stock"
    74        tags:
    75        - pets
    76        - users
    77        consumes:
    78        - application/json
    79        - application/x-protobuf
    80        produces:
    81        - application/json
    82        - application/x-protobuf
    83        schemes:
    84        - http
    85        - https
    86        - ws
    87        - wss
    88        security:
    89          api_key: []
    90          oauth:
    91          - read
    92          - write
    93        responses:
    94          default:
    95            $ref: "#/responses/genericError"
    96          200:
    97            $ref: "#/responses/someResponse"
    98          422:
    99            $ref: "#/responses/validationError"
   100  ```