github.com/astaxie/beego@v1.12.3/swagger/swagger.go (about) 1 // Copyright 2014 beego Author. All Rights Reserved. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 // 15 // Swagger™ is a project used to describe and document RESTful APIs. 16 // 17 // The Swagger specification defines a set of files required to describe such an API. These files can then be used by the Swagger-UI project to display the API and Swagger-Codegen to generate clients in various languages. Additional utilities can also take advantage of the resulting files, such as testing tools. 18 // Now in version 2.0, Swagger is more enabling than ever. And it's 100% open source software. 19 20 // Package swagger struct definition 21 package swagger 22 23 // Swagger list the resource 24 type Swagger struct { 25 SwaggerVersion string `json:"swagger,omitempty" yaml:"swagger,omitempty"` 26 Infos Information `json:"info" yaml:"info"` 27 Host string `json:"host,omitempty" yaml:"host,omitempty"` 28 BasePath string `json:"basePath,omitempty" yaml:"basePath,omitempty"` 29 Schemes []string `json:"schemes,omitempty" yaml:"schemes,omitempty"` 30 Consumes []string `json:"consumes,omitempty" yaml:"consumes,omitempty"` 31 Produces []string `json:"produces,omitempty" yaml:"produces,omitempty"` 32 Paths map[string]*Item `json:"paths" yaml:"paths"` 33 Definitions map[string]Schema `json:"definitions,omitempty" yaml:"definitions,omitempty"` 34 SecurityDefinitions map[string]Security `json:"securityDefinitions,omitempty" yaml:"securityDefinitions,omitempty"` 35 Security []map[string][]string `json:"security,omitempty" yaml:"security,omitempty"` 36 Tags []Tag `json:"tags,omitempty" yaml:"tags,omitempty"` 37 ExternalDocs *ExternalDocs `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"` 38 } 39 40 // Information Provides metadata about the API. The metadata can be used by the clients if needed. 41 type Information struct { 42 Title string `json:"title,omitempty" yaml:"title,omitempty"` 43 Description string `json:"description,omitempty" yaml:"description,omitempty"` 44 Version string `json:"version,omitempty" yaml:"version,omitempty"` 45 TermsOfService string `json:"termsOfService,omitempty" yaml:"termsOfService,omitempty"` 46 47 Contact Contact `json:"contact,omitempty" yaml:"contact,omitempty"` 48 License *License `json:"license,omitempty" yaml:"license,omitempty"` 49 } 50 51 // Contact information for the exposed API. 52 type Contact struct { 53 Name string `json:"name,omitempty" yaml:"name,omitempty"` 54 URL string `json:"url,omitempty" yaml:"url,omitempty"` 55 EMail string `json:"email,omitempty" yaml:"email,omitempty"` 56 } 57 58 // License information for the exposed API. 59 type License struct { 60 Name string `json:"name,omitempty" yaml:"name,omitempty"` 61 URL string `json:"url,omitempty" yaml:"url,omitempty"` 62 } 63 64 // Item Describes the operations available on a single path. 65 type Item struct { 66 Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"` 67 Get *Operation `json:"get,omitempty" yaml:"get,omitempty"` 68 Put *Operation `json:"put,omitempty" yaml:"put,omitempty"` 69 Post *Operation `json:"post,omitempty" yaml:"post,omitempty"` 70 Delete *Operation `json:"delete,omitempty" yaml:"delete,omitempty"` 71 Options *Operation `json:"options,omitempty" yaml:"options,omitempty"` 72 Head *Operation `json:"head,omitempty" yaml:"head,omitempty"` 73 Patch *Operation `json:"patch,omitempty" yaml:"patch,omitempty"` 74 } 75 76 // Operation Describes a single API operation on a path. 77 type Operation struct { 78 Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"` 79 Summary string `json:"summary,omitempty" yaml:"summary,omitempty"` 80 Description string `json:"description,omitempty" yaml:"description,omitempty"` 81 OperationID string `json:"operationId,omitempty" yaml:"operationId,omitempty"` 82 Consumes []string `json:"consumes,omitempty" yaml:"consumes,omitempty"` 83 Produces []string `json:"produces,omitempty" yaml:"produces,omitempty"` 84 Schemes []string `json:"schemes,omitempty" yaml:"schemes,omitempty"` 85 Parameters []Parameter `json:"parameters,omitempty" yaml:"parameters,omitempty"` 86 Responses map[string]Response `json:"responses,omitempty" yaml:"responses,omitempty"` 87 Security []map[string][]string `json:"security,omitempty" yaml:"security,omitempty"` 88 Deprecated bool `json:"deprecated,omitempty" yaml:"deprecated,omitempty"` 89 } 90 91 // Parameter Describes a single operation parameter. 92 type Parameter struct { 93 In string `json:"in,omitempty" yaml:"in,omitempty"` 94 Name string `json:"name,omitempty" yaml:"name,omitempty"` 95 Description string `json:"description,omitempty" yaml:"description,omitempty"` 96 Required bool `json:"required,omitempty" yaml:"required,omitempty"` 97 Schema *Schema `json:"schema,omitempty" yaml:"schema,omitempty"` 98 Type string `json:"type,omitempty" yaml:"type,omitempty"` 99 Format string `json:"format,omitempty" yaml:"format,omitempty"` 100 Items *ParameterItems `json:"items,omitempty" yaml:"items,omitempty"` 101 Default interface{} `json:"default,omitempty" yaml:"default,omitempty"` 102 } 103 104 // ParameterItems A limited subset of JSON-Schema's items object. It is used by parameter definitions that are not located in "body". 105 // http://swagger.io/specification/#itemsObject 106 type ParameterItems struct { 107 Type string `json:"type,omitempty" yaml:"type,omitempty"` 108 Format string `json:"format,omitempty" yaml:"format,omitempty"` 109 Items []*ParameterItems `json:"items,omitempty" yaml:"items,omitempty"` //Required if type is "array". Describes the type of items in the array. 110 CollectionFormat string `json:"collectionFormat,omitempty" yaml:"collectionFormat,omitempty"` 111 Default string `json:"default,omitempty" yaml:"default,omitempty"` 112 } 113 114 // Schema Object allows the definition of input and output data types. 115 type Schema struct { 116 Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"` 117 Title string `json:"title,omitempty" yaml:"title,omitempty"` 118 Format string `json:"format,omitempty" yaml:"format,omitempty"` 119 Description string `json:"description,omitempty" yaml:"description,omitempty"` 120 Required []string `json:"required,omitempty" yaml:"required,omitempty"` 121 Type string `json:"type,omitempty" yaml:"type,omitempty"` 122 Items *Schema `json:"items,omitempty" yaml:"items,omitempty"` 123 Properties map[string]Propertie `json:"properties,omitempty" yaml:"properties,omitempty"` 124 Enum []interface{} `json:"enum,omitempty" yaml:"enum,omitempty"` 125 Example interface{} `json:"example,omitempty" yaml:"example,omitempty"` 126 } 127 128 // Propertie are taken from the JSON Schema definition but their definitions were adjusted to the Swagger Specification 129 type Propertie struct { 130 Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"` 131 Title string `json:"title,omitempty" yaml:"title,omitempty"` 132 Description string `json:"description,omitempty" yaml:"description,omitempty"` 133 Default interface{} `json:"default,omitempty" yaml:"default,omitempty"` 134 Type string `json:"type,omitempty" yaml:"type,omitempty"` 135 Example interface{} `json:"example,omitempty" yaml:"example,omitempty"` 136 Required []string `json:"required,omitempty" yaml:"required,omitempty"` 137 Format string `json:"format,omitempty" yaml:"format,omitempty"` 138 ReadOnly bool `json:"readOnly,omitempty" yaml:"readOnly,omitempty"` 139 Properties map[string]Propertie `json:"properties,omitempty" yaml:"properties,omitempty"` 140 Items *Propertie `json:"items,omitempty" yaml:"items,omitempty"` 141 AdditionalProperties *Propertie `json:"additionalProperties,omitempty" yaml:"additionalProperties,omitempty"` 142 } 143 144 // Response as they are returned from executing this operation. 145 type Response struct { 146 Description string `json:"description" yaml:"description"` 147 Schema *Schema `json:"schema,omitempty" yaml:"schema,omitempty"` 148 Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"` 149 } 150 151 // Security Allows the definition of a security scheme that can be used by the operations 152 type Security struct { 153 Type string `json:"type,omitempty" yaml:"type,omitempty"` // Valid values are "basic", "apiKey" or "oauth2". 154 Description string `json:"description,omitempty" yaml:"description,omitempty"` 155 Name string `json:"name,omitempty" yaml:"name,omitempty"` 156 In string `json:"in,omitempty" yaml:"in,omitempty"` // Valid values are "query" or "header". 157 Flow string `json:"flow,omitempty" yaml:"flow,omitempty"` // Valid values are "implicit", "password", "application" or "accessCode". 158 AuthorizationURL string `json:"authorizationUrl,omitempty" yaml:"authorizationUrl,omitempty"` 159 TokenURL string `json:"tokenUrl,omitempty" yaml:"tokenUrl,omitempty"` 160 Scopes map[string]string `json:"scopes,omitempty" yaml:"scopes,omitempty"` // The available scopes for the OAuth2 security scheme. 161 } 162 163 // Tag Allows adding meta data to a single tag that is used by the Operation Object 164 type Tag struct { 165 Name string `json:"name,omitempty" yaml:"name,omitempty"` 166 Description string `json:"description,omitempty" yaml:"description,omitempty"` 167 ExternalDocs *ExternalDocs `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"` 168 } 169 170 // ExternalDocs include Additional external documentation 171 type ExternalDocs struct { 172 Description string `json:"description,omitempty" yaml:"description,omitempty"` 173 URL string `json:"url,omitempty" yaml:"url,omitempty"` 174 }