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