swagger.go 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171
  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. // Package swagger struct definition
  20. package swagger
  21. // Swagger list the resource
  22. type Swagger struct {
  23. SwaggerVersion string `json:"swagger,omitempty" yaml:"swagger,omitempty"`
  24. Infos Information `json:"info" yaml:"info"`
  25. Host string `json:"host,omitempty" yaml:"host,omitempty"`
  26. BasePath string `json:"basePath,omitempty" yaml:"basePath,omitempty"`
  27. Schemes []string `json:"schemes,omitempty" yaml:"schemes,omitempty"`
  28. Consumes []string `json:"consumes,omitempty" yaml:"consumes,omitempty"`
  29. Produces []string `json:"produces,omitempty" yaml:"produces,omitempty"`
  30. Paths map[string]*Item `json:"paths" yaml:"paths"`
  31. Definitions map[string]Schema `json:"definitions,omitempty" yaml:"definitions,omitempty"`
  32. SecurityDefinitions map[string]Security `json:"securityDefinitions,omitempty" yaml:"securityDefinitions,omitempty"`
  33. Security map[string][]string `json:"security,omitempty" yaml:"security,omitempty"`
  34. Tags []Tag `json:"tags,omitempty" yaml:"tags,omitempty"`
  35. ExternalDocs *ExternalDocs `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
  36. }
  37. // Information Provides metadata about the API. The metadata can be used by the clients if needed.
  38. type Information struct {
  39. Title string `json:"title,omitempty" yaml:"title,omitempty"`
  40. Description string `json:"description,omitempty" yaml:"description,omitempty"`
  41. Version string `json:"version,omitempty" yaml:"version,omitempty"`
  42. TermsOfService string `json:"termsOfService,omitempty" yaml:"termsOfService,omitempty"`
  43. Contact Contact `json:"contact,omitempty" yaml:"contact,omitempty"`
  44. License *License `json:"license,omitempty" yaml:"license,omitempty"`
  45. }
  46. // Contact information for the exposed API.
  47. type Contact struct {
  48. Name string `json:"name,omitempty" yaml:"name,omitempty"`
  49. URL string `json:"url,omitempty" yaml:"url,omitempty"`
  50. EMail string `json:"email,omitempty" yaml:"email,omitempty"`
  51. }
  52. // License information for the exposed API.
  53. type License struct {
  54. Name string `json:"name,omitempty" yaml:"name,omitempty"`
  55. URL string `json:"url,omitempty" yaml:"url,omitempty"`
  56. }
  57. // Item Describes the operations available on a single path.
  58. type Item struct {
  59. Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`
  60. Get *Operation `json:"get,omitempty" yaml:"get,omitempty"`
  61. Put *Operation `json:"put,omitempty" yaml:"put,omitempty"`
  62. Post *Operation `json:"post,omitempty" yaml:"post,omitempty"`
  63. Delete *Operation `json:"delete,omitempty" yaml:"delete,omitempty"`
  64. Options *Operation `json:"options,omitempty" yaml:"options,omitempty"`
  65. Head *Operation `json:"head,omitempty" yaml:"head,omitempty"`
  66. Patch *Operation `json:"patch,omitempty" yaml:"patch,omitempty"`
  67. }
  68. // Operation Describes a single API operation on a path.
  69. type Operation struct {
  70. Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`
  71. Summary string `json:"summary,omitempty" yaml:"summary,omitempty"`
  72. Description string `json:"description,omitempty" yaml:"description,omitempty"`
  73. OperationID string `json:"operationId,omitempty" yaml:"operationId,omitempty"`
  74. Consumes []string `json:"consumes,omitempty" yaml:"consumes,omitempty"`
  75. Produces []string `json:"produces,omitempty" yaml:"produces,omitempty"`
  76. Schemes []string `json:"schemes,omitempty" yaml:"schemes,omitempty"`
  77. Parameters []Parameter `json:"parameters,omitempty" yaml:"parameters,omitempty"`
  78. Responses map[string]Response `json:"responses,omitempty" yaml:"responses,omitempty"`
  79. Deprecated bool `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
  80. }
  81. // Parameter Describes a single operation parameter.
  82. type Parameter struct {
  83. In string `json:"in,omitempty" yaml:"in,omitempty"`
  84. Name string `json:"name,omitempty" yaml:"name,omitempty"`
  85. Description string `json:"description,omitempty" yaml:"description,omitempty"`
  86. Required bool `json:"required,omitempty" yaml:"required,omitempty"`
  87. Schema *Schema `json:"schema,omitempty" yaml:"schema,omitempty"`
  88. Type string `json:"type,omitempty" yaml:"type,omitempty"`
  89. Format string `json:"format,omitempty" yaml:"format,omitempty"`
  90. Items *ParameterItems `json:"items,omitempty" yaml:"items,omitempty"`
  91. Default interface{} `json:"default,omitempty" yaml:"default,omitempty"`
  92. }
  93. // A limited subset of JSON-Schema's items object. It is used by parameter definitions that are not located in "body".
  94. // http://swagger.io/specification/#itemsObject
  95. type ParameterItems struct {
  96. Type string `json:"type,omitempty" yaml:"type,omitempty"`
  97. Format string `json:"format,omitempty" yaml:"format,omitempty"`
  98. Items []*ParameterItems `json:"items,omitempty" yaml:"items,omitempty"` //Required if type is "array". Describes the type of items in the array.
  99. CollectionFormat string `json:"collectionFormat,omitempty" yaml:"collectionFormat,omitempty"`
  100. Default string `json:"default,omitempty" yaml:"default,omitempty"`
  101. }
  102. // Schema Object allows the definition of input and output data types.
  103. type Schema struct {
  104. Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`
  105. Title string `json:"title,omitempty" yaml:"title,omitempty"`
  106. Format string `json:"format,omitempty" yaml:"format,omitempty"`
  107. Description string `json:"description,omitempty" yaml:"description,omitempty"`
  108. Required []string `json:"required,omitempty" yaml:"required,omitempty"`
  109. Type string `json:"type,omitempty" yaml:"type,omitempty"`
  110. Items *Schema `json:"items,omitempty" yaml:"items,omitempty"`
  111. Properties map[string]Propertie `json:"properties,omitempty" yaml:"properties,omitempty"`
  112. }
  113. // Propertie are taken from the JSON Schema definition but their definitions were adjusted to the Swagger Specification
  114. type Propertie struct {
  115. Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`
  116. Title string `json:"title,omitempty" yaml:"title,omitempty"`
  117. Description string `json:"description,omitempty" yaml:"description,omitempty"`
  118. Default interface{} `json:"default,omitempty" yaml:"default,omitempty"`
  119. Type string `json:"type,omitempty" yaml:"type,omitempty"`
  120. Example string `json:"example,omitempty" yaml:"example,omitempty"`
  121. Required []string `json:"required,omitempty" yaml:"required,omitempty"`
  122. Format string `json:"format,omitempty" yaml:"format,omitempty"`
  123. ReadOnly bool `json:"readOnly,omitempty" yaml:"readOnly,omitempty"`
  124. Properties map[string]Propertie `json:"properties,omitempty" yaml:"properties,omitempty"`
  125. Items *Propertie `json:"items,omitempty" yaml:"items,omitempty"`
  126. AdditionalProperties *Propertie `json:"additionalProperties,omitempty" yaml:"additionalProperties,omitempty"`
  127. }
  128. // Response as they are returned from executing this operation.
  129. type Response struct {
  130. Description string `json:"description,omitempty" yaml:"description,omitempty"`
  131. Schema *Schema `json:"schema,omitempty" yaml:"schema,omitempty"`
  132. Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`
  133. }
  134. // Security Allows the definition of a security scheme that can be used by the operations
  135. type Security struct {
  136. Type string `json:"type,omitempty" yaml:"type,omitempty"` // Valid values are "basic", "apiKey" or "oauth2".
  137. Description string `json:"description,omitempty" yaml:"description,omitempty"`
  138. Name string `json:"name,omitempty" yaml:"name,omitempty"`
  139. In string `json:"in,omitempty" yaml:"in,omitempty"` // Valid values are "query" or "header".
  140. Flow string `json:"flow,omitempty" yaml:"flow,omitempty"` // Valid values are "implicit", "password", "application" or "accessCode".
  141. AuthorizationURL string `json:"authorizationUrl,omitempty" yaml:"authorizationUrl,omitempty"`
  142. TokenURL string `json:"tokenUrl,omitempty" yaml:"tokenUrl,omitempty"`
  143. Scopes map[string]string `json:"scopes,omitempty" yaml:"scopes,omitempty"` // The available scopes for the OAuth2 security scheme.
  144. }
  145. // Tag Allows adding meta data to a single tag that is used by the Operation Object
  146. type Tag struct {
  147. Name string `json:"name,omitempty" yaml:"name,omitempty"`
  148. Description string `json:"description,omitempty" yaml:"description,omitempty"`
  149. ExternalDocs *ExternalDocs `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
  150. }
  151. // ExternalDocs include Additional external documentation
  152. type ExternalDocs struct {
  153. Description string `json:"description,omitempty" yaml:"description,omitempty"`
  154. URL string `json:"url,omitempty" yaml:"url,omitempty"`
  155. }