github.com/AngusLu/go-swagger@v0.28.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  **Deprecated** | Route marked as deprecated if this value is true
    27  **Security** | a dictionary of key: []string{scopes}
    28  **Responses** | a dictionary of status code to named response
    29  
    30  ##### Example:
    31  
    32  ```go
    33  // ServeAPI serves the API for this record store
    34  func ServeAPI(host, basePath string, schemes []string) error {
    35  
    36  	// swagger:route GET /pets pets users listPets
    37  	//
    38  	// Lists pets filtered by some parameters.
    39  	//
    40  	// This will show all available pets by default.
    41  	// You can get the pets that are out of stock
    42  	//
    43  	//     Consumes:
    44  	//     - application/json
    45  	//     - application/x-protobuf
    46  	//
    47  	//     Produces:
    48  	//     - application/json
    49  	//     - application/x-protobuf
    50  	//
    51  	//     Schemes: http, https, ws, wss
    52  	//
    53  	//     Deprecated: true
    54  	//
    55  	//     Security:
    56  	//       api_key:
    57  	//       oauth: read, write
    58  	//
    59  	//     Responses:
    60  	//       default: genericError
    61  	//       200: someResponse
    62  	//       422: validationError
    63  	mountItem("GET", basePath+"/pets", nil)
    64  }
    65  ```
    66  
    67  ##### Result:
    68  
    69  ```yaml
    70  ---
    71  paths:
    72    "/pets":
    73      get:
    74        operationId: listPets
    75        deprecated: true
    76        summary: Lists pets filtered by some parameters.
    77        description: "This will show all available pets by default.\nYou can get the pets that are out of stock"
    78        tags:
    79        - pets
    80        - users
    81        consumes:
    82        - application/json
    83        - application/x-protobuf
    84        produces:
    85        - application/json
    86        - application/x-protobuf
    87        schemes:
    88        - http
    89        - https
    90        - ws
    91        - wss
    92        security:
    93          api_key: []
    94          oauth:
    95          - read
    96          - write
    97        responses:
    98          default:
    99            $ref: "#/responses/genericError"
   100          200:
   101            $ref: "#/responses/someResponse"
   102          422:
   103            $ref: "#/responses/validationError"
   104  ```