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 ```