github.com/kaisawind/go-swagger@v0.19.0/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 **Terms Of Service** | allows for either a url or a free text definition describing the terms of services for the API 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 ##### Result 99 100 ```yaml 101 --- 102 swagger: '2.0' 103 consumes: 104 - application/json 105 - application/xml 106 produces: 107 - application/json 108 - application/xml 109 schemes: 110 - http 111 - https 112 info: 113 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" 114 title: 'Petstore API.' 115 termsOfService: 'there are no TOS at this moment, use at your own risk we take no responsibility' 116 contact: {name: 'John Doe', url: 'http://john.doe.com', email: john.doe@example.com} 117 license: {name: MIT, url: 'http://opensource.org/licenses/MIT'} 118 version: 0.0.1 119 host: localhost 120 basePath: /v2 121 x-meta-value: value 122 x-meta-array: 123 - value1 124 - value2 125 x-meta-array-obj: 126 - name: obj 127 value: field 128 ``` 129 130 ##### Supported MIME types 131 132 Consumes | Produces 133 --------------|--------- 134 json | json 135 yaml | yaml 136 xml | xml 137 txt | txt 138 bin | bin 139 urlform | urlform 140 multipartform | multipartform 141 142 [Source](https://github.com/go-swagger/go-swagger/blob/7485a982b539bedd870bd56a487e37c8decd7f2c/generator/support.go#L317-L335)