github.com/thetreep/go-swagger@v0.0.0-20240223100711-35af64f14f01/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  **Parameters** | a list of parameters that this API accepts
    29  **Responses** | a dictionary of status code to named response
    30  **Extensions** | a dictionary of custom [vendor extensions](https://swagger.io/docs/specification/2-0/swagger-extensions/); each key must start with `x-`
    31  
    32  ##### Example:
    33  
    34  ```go
    35  // ServeAPI serves the API for this record store
    36  func ServeAPI(host, basePath string, schemes []string) error {
    37  
    38  	// swagger:route GET /pets pets users listPets
    39  	//
    40  	// Lists pets filtered by some parameters.
    41  	//
    42  	// This will show all available pets by default.
    43  	// You can get the pets that are out of stock
    44  	//
    45  	//     Consumes:
    46  	//     - application/json
    47  	//     - application/x-protobuf
    48  	//
    49  	//     Produces:
    50  	//     - application/json
    51  	//     - application/x-protobuf
    52  	//
    53  	//     Schemes: http, https, ws, wss
    54  	//
    55  	//     Deprecated: true
    56  	//
    57  	//     Security:
    58  	//       api_key:
    59  	//       oauth: read, write
    60  	//
    61    //     Parameters:
    62    //       + name: limit
    63    //         in: query
    64    //         description: maximum umber of results to return
    65    //         required: false
    66    //         type: integer
    67    //         format: int32
    68    //
    69  	//     Responses:
    70  	//       default: genericError
    71  	//       200: someResponse
    72  	//       422: validationError
    73    //     Extensions:
    74    //       x-example-flag: true
    75    //       x-some-list:
    76    //         - dog
    77    //         - cat
    78    //         - bird
    79  	mountItem("GET", basePath+"/pets", nil)
    80  }
    81  ```
    82  
    83  ##### Result:
    84  
    85  ```yaml
    86  ---
    87  paths:
    88    "/pets":
    89      get:
    90        operationId: listPets
    91        deprecated: true
    92        summary: Lists pets filtered by some parameters.
    93        description: "This will show all available pets by default.\nYou can get the pets that are out of stock"
    94        tags:
    95        - pets
    96        - users
    97        consumes:
    98        - application/json
    99        - application/x-protobuf
   100        produces:
   101        - application/json
   102        - application/x-protobuf
   103        schemes:
   104        - http
   105        - https
   106        - ws
   107        - wss
   108        security:
   109          api_key: []
   110          oauth:
   111          - read
   112          - write
   113        parameters:
   114          description: maximum number of results to return
   115          format: int43
   116          in: query
   117          name: limit
   118          type: integer
   119        responses:
   120          default:
   121            $ref: "#/responses/genericError"
   122          200:
   123            $ref: "#/responses/someResponse"
   124          422:
   125            $ref: "#/responses/validationError"
   126        extensions:
   127          x-example-flag: true
   128          x-some-list:
   129          - dog
   130          - cat
   131          - bird
   132  ```