github.com/josephspurrier/go-swagger@v0.2.1-0.20221129144919-1f672a142a00/docs/use/spec/meta.md (about) 1 # swagger:meta 2 3 The **swagger:meta** annotation flags a file as source for metadata about the API. 4 This is typically a doc.go file with your package documentation. 5 6 You can specify a Consumes and Produces key which has a new content type on each line 7 Schemes is a tag that is required and allows for a comma separated string composed of: 8 http, https, ws or wss 9 10 Host and BasePath can be specified but those values will be defaults, 11 they should get substituted when serving the swagger spec. 12 13 The description property uses the rest of the comment block as description for the api when not explicitly provided 14 15 ##### Syntax: 16 17 ``` 18 swagger:meta 19 ``` 20 21 ##### Properties: 22 23 Annotation | Format 24 -----------|-------- 25 **TermsOfService** | allows for either a url or a free text definition describing the terms of services for the API (alias **"TOS"**) 26 **Consumes** | a list of default (global) mime type values, one per line, for the content the API receives.<br>[List of supported mime types](#supported-mime-types) 27 **Produces** | a list of default (global) mime type values, one per line, for the content the API sends.<br>[List of supported mime types](#supported-mime-types) 28 **Schemes** | a list of default schemes the API accept (possible values: http, https, ws, wss) https is preferred as default when configured 29 **Version** | the current version of the API 30 **Host** | the host from where the spec is served 31 **Base path** | the default base path for this API 32 **Contact** | the name of for the person to contact concerning the API eg. John Doe <john@blogs.com> http://john.blogs.com 33 **License** | the name of the license followed by the URL of the license eg. MIT http://opensource.org/license/MIT 34 **Security** | a dictionary of key: []string{scopes} 35 **SecurityDefinitions** | list of supported authorization types https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securityDefinitionsObject 36 **Extensions** | list of extensions to Swagger Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. 37 38 ##### Example: 39 40 ```go 41 // Package classification Petstore API. 42 // 43 // the purpose of this application is to provide an application 44 // that is using plain go code to define an API 45 // 46 // This should demonstrate all the possible comment annotations 47 // that are available to turn go code into a fully compliant swagger 2.0 spec 48 // 49 // Terms Of Service: 50 // 51 // there are no TOS at this moment, use at your own risk we take no responsibility 52 // 53 // Schemes: http, https 54 // Host: localhost 55 // BasePath: /v2 56 // Version: 0.0.1 57 // License: MIT http://opensource.org/licenses/MIT 58 // Contact: John Doe<john.doe@example.com> http://john.doe.com 59 // 60 // Consumes: 61 // - application/json 62 // - application/xml 63 // 64 // Produces: 65 // - application/json 66 // - application/xml 67 // 68 // Security: 69 // - api_key: 70 // 71 // SecurityDefinitions: 72 // api_key: 73 // type: apiKey 74 // name: KEY 75 // in: header 76 // oauth2: 77 // type: oauth2 78 // authorizationUrl: /oauth2/auth 79 // tokenUrl: /oauth2/token 80 // in: header 81 // scopes: 82 // bar: foo 83 // flow: accessCode 84 // 85 // Extensions: 86 // x-meta-value: value 87 // x-meta-array: 88 // - value1 89 // - value2 90 // x-meta-array-obj: 91 // - name: obj 92 // value: field 93 // 94 // swagger:meta 95 package classification 96 ``` 97 98 > **NOTE:** If there is whitespace line between the comment and package (or type, function), swagger will generate an empty specification. This is due to the violation of the convention for Godoc. For more details refer [here](https://blog.golang.org/godoc) 99 100 ##### Result 101 102 ```yaml 103 --- 104 swagger: '2.0' 105 consumes: 106 - application/json 107 - application/xml 108 produces: 109 - application/json 110 - application/xml 111 schemes: 112 - http 113 - https 114 info: 115 description: "the purpose of this application is to provide an application\nthat is using plain go code to define an API\n\nThis should demonstrate all the possible comment annotations\nthat are available to turn go code into a fully compliant swagger 2.0 spec" 116 title: 'Petstore API.' 117 termsOfService: 'there are no TOS at this moment, use at your own risk we take no responsibility' 118 contact: {name: 'John Doe', url: 'http://john.doe.com', email: john.doe@example.com} 119 license: {name: MIT, url: 'http://opensource.org/licenses/MIT'} 120 version: 0.0.1 121 host: localhost 122 basePath: /v2 123 x-meta-value: value 124 x-meta-array: 125 - value1 126 - value2 127 x-meta-array-obj: 128 - name: obj 129 value: field 130 ``` 131 132 ##### Supported MIME types 133 134 Consumes | Produces 135 --------------|--------- 136 json | json 137 yaml | yaml 138 xml | xml 139 txt | txt 140 bin | bin 141 urlform | urlform 142 multipartform | multipartform 143 144 [Source](https://github.com/go-swagger/go-swagger/blob/7485a982b539bedd870bd56a487e37c8decd7f2c/generator/support.go#L317-L335)