upgrade swagger from 1.2 to 2.0

beego.go

@@ -72,7 +72,6 @@ func initBeforeHTTPRun() {
 	AddAPPStartHook(registerMime)
 	AddAPPStartHook(registerDefaultErrorHandler)
 	AddAPPStartHook(registerSession)
-	AddAPPStartHook(registerDocs)
 	AddAPPStartHook(registerTemplate)
 	AddAPPStartHook(registerAdmin)
 	AddAPPStartHook(registerGzip)

docs.go

-// Copyright 2014 beego Author. All Rights Reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//      http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package beego
-
-import (
-	"github.com/astaxie/beego/context"
-)
-
-// GlobalDocAPI store the swagger api documents
-var GlobalDocAPI = make(map[string]interface{})
-
-func serverDocs(ctx *context.Context) {
-	var obj interface{}
-	if splat := ctx.Input.Param(":splat"); splat == "" {
-		obj = GlobalDocAPI["Root"]
-	} else {
-		if v, ok := GlobalDocAPI[splat]; ok {
-			obj = v
-		}
-	}
-	if obj != nil {
-		ctx.Output.Header("Access-Control-Allow-Origin", "*")
-		ctx.Output.JSON(obj, false, false)
-		return
-	}
-	ctx.Output.SetStatus(404)
-}

hooks.go

@@ -79,14 +79,6 @@ func registerTemplate() error {
 	return nil
 }
 
-func registerDocs() error {
-	if BConfig.WebConfig.EnableDocs {
-		Get("/docs", serverDocs)
-		Get("/docs/*", serverDocs)
-	}
-	return nil
-}
-
 func registerAdmin() error {
 	if BConfig.Listen.EnableAdmin {
 		go beeAdminApp.Run()

swagger/docs_spec.go

-// Copyright 2014 beego Author. All Rights Reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//      http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-// Package swagger struct definition
-package swagger
-
-// SwaggerVersion show the current swagger version
-const SwaggerVersion = "1.2"
-
-// ResourceListing list the resource
-type ResourceListing struct {
-	APIVersion     string `json:"apiVersion"`
-	SwaggerVersion string `json:"swaggerVersion"` // e.g 1.2
-	// BasePath       string `json:"basePath"`  obsolete in 1.1
-	APIs []APIRef    `json:"apis"`
-	Info Information `json:"info"`
-}
-
-// APIRef description the api path and description
-type APIRef struct {
-	Path        string `json:"path"` // relative or absolute, must start with /
-	Description string `json:"description"`
-}
-
-// Information show the API Information
-type Information struct {
-	Title             string `json:"title,omitempty"`
-	Description       string `json:"description,omitempty"`
-	Contact           string `json:"contact,omitempty"`
-	TermsOfServiceURL string `json:"termsOfServiceUrl,omitempty"`
-	License           string `json:"license,omitempty"`
-	LicenseURL        string `json:"licenseUrl,omitempty"`
-}
-
-// APIDeclaration see https://github.com/wordnik/swagger-core/blob/scala_2.10-1.3-RC3/schemas/api-declaration-schema.json
-type APIDeclaration struct {
-	APIVersion     string           `json:"apiVersion"`
-	SwaggerVersion string           `json:"swaggerVersion"`
-	BasePath       string           `json:"basePath"`
-	ResourcePath   string           `json:"resourcePath"` // must start with /
-	Consumes       []string         `json:"consumes,omitempty"`
-	Produces       []string         `json:"produces,omitempty"`
-	APIs           []API            `json:"apis,omitempty"`
-	Models         map[string]Model `json:"models,omitempty"`
-}
-
-// API show tha API struct
-type API struct {
-	Path        string      `json:"path"` // relative or absolute, must start with /
-	Description string      `json:"description"`
-	Operations  []Operation `json:"operations,omitempty"`
-}
-
-// Operation desc the Operation
-type Operation struct {
-	HTTPMethod string `json:"httpMethod"`
-	Nickname   string `json:"nickname"`
-	Type       string `json:"type"` // in 1.1 = DataType
-	// ResponseClass    string            `json:"responseClass"` obsolete in 1.2
-	Summary          string            `json:"summary,omitempty"`
-	Notes            string            `json:"notes,omitempty"`
-	Parameters       []Parameter       `json:"parameters,omitempty"`
-	ResponseMessages []ResponseMessage `json:"responseMessages,omitempty"` // optional
-	Consumes         []string          `json:"consumes,omitempty"`
-	Produces         []string          `json:"produces,omitempty"`
-	Authorizations   []Authorization   `json:"authorizations,omitempty"`
-	Protocols        []Protocol        `json:"protocols,omitempty"`
-}
-
-// Protocol support which Protocol
-type Protocol struct {
-}
-
-// ResponseMessage Show the
-type ResponseMessage struct {
-	Code          int    `json:"code"`
-	Message       string `json:"message"`
-	ResponseModel string `json:"responseModel"`
-}
-
-// Parameter desc the request parameters
-type Parameter struct {
-	ParamType     string `json:"paramType"` // path,query,body,header,form
-	Name          string `json:"name"`
-	Description   string `json:"description"`
-	DataType      string `json:"dataType"` // 1.2 needed?
-	Type          string `json:"type"`     // integer
-	Format        string `json:"format"`   // int64
-	AllowMultiple bool   `json:"allowMultiple"`
-	Required      bool   `json:"required"`
-	Minimum       int    `json:"minimum"`
-	Maximum       int    `json:"maximum"`
-}
-
-// ErrorResponse desc response
-type ErrorResponse struct {
-	Code   int    `json:"code"`
-	Reason string `json:"reason"`
-}
-
-// Model define the data model
-type Model struct {
-	ID         string                   `json:"id"`
-	Required   []string                 `json:"required,omitempty"`
-	Properties map[string]ModelProperty `json:"properties"`
-}
-
-// ModelProperty define the properties
-type ModelProperty struct {
-	Type        string            `json:"type"`
-	Description string            `json:"description"`
-	Items       map[string]string `json:"items,omitempty"`
-	Format      string            `json:"format"`
-}
-
-// Authorization see https://github.com/wordnik/swagger-core/wiki/authorizations
-type Authorization struct {
-	LocalOAuth OAuth  `json:"local-oauth"`
-	APIKey     APIKey `json:"apiKey"`
-}
-
-// OAuth see https://github.com/wordnik/swagger-core/wiki/authorizations
-type OAuth struct {
-	Type       string               `json:"type"`   // e.g. oauth2
-	Scopes     []string             `json:"scopes"` // e.g. PUBLIC
-	GrantTypes map[string]GrantType `json:"grantTypes"`
-}
-
-// GrantType see https://github.com/wordnik/swagger-core/wiki/authorizations
-type GrantType struct {
-	LoginEndpoint        Endpoint `json:"loginEndpoint"`
-	TokenName            string   `json:"tokenName"` // e.g. access_code
-	TokenRequestEndpoint Endpoint `json:"tokenRequestEndpoint"`
-	TokenEndpoint        Endpoint `json:"tokenEndpoint"`
-}
-
-// Endpoint see https://github.com/wordnik/swagger-core/wiki/authorizations
-type Endpoint struct {
-	URL              string `json:"url"`
-	ClientIDName     string `json:"clientIdName"`
-	ClientSecretName string `json:"clientSecretName"`
-	TokenName        string `json:"tokenName"`
-}
-
-// APIKey see https://github.com/wordnik/swagger-core/wiki/authorizations
-type APIKey struct {
-	Type   string `json:"type"`   // e.g. apiKey
-	PassAs string `json:"passAs"` // e.g. header
-}

swagger/swagger.go

+// Copyright 2014 beego Author. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Swagger™ is a project used to describe and document RESTful APIs.
+//
+// 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.
+// Now in version 2.0, Swagger is more enabling than ever. And it's 100% open source software.
+
+// Package swagger struct definition
+package swagger
+
+// Swagger list the resource
+type Swagger struct {
+	SwaggerVersion      string              `json:"swagger,omitempty"`
+	Infos               Information         `json:"info"`
+	Host                string              `json:"host,omitempty"`
+	BasePath            string              `json:"basePath,omitempty"`
+	Schemes             []string            `json:"schemes,omitempty"`
+	Consumes            []string            `json:"consumes,omitempty"`
+	Produces            []string            `json:"produces,omitempty"`
+	Paths               map[string]Item     `json:"paths"`
+	Definitions         map[string]Schema   `json:"definitions,omitempty"`
+	SecurityDefinitions map[string]Scurity  `json:"securityDefinitions,omitempty"`
+	Security            map[string][]string `json:"security,omitempty"`
+	Tags                []Tag               `json:"tags,omitempty"`
+	ExternalDocs        ExternalDocs        `json:"externalDocs,omitempty"`
+}
+
+// Information Provides metadata about the API. The metadata can be used by the clients if needed.
+type Information struct {
+	Title             string `json:"title,omitempty"`
+	Description       string `json:"description,omitempty"`
+	Version           string `json:"version,omitempty"`
+	TermsOfServiceURL string `json:"termsOfServiceUrl,omitempty"`
+
+	Contact Contact `json:"contact,omitempty"`
+	License License `json:"license,omitempty"`
+}
+
+// Contact information for the exposed API.
+type Contact struct {
+	Name  string `json:"name,omitempty"`
+	URL   string `json:"url,omitempty"`
+	EMail string `json:"email,omitempty"`
+}
+
+// License information for the exposed API.
+type License struct {
+	Name string `json:"name,omitempty"`
+	URL  string `json:"url,omitempty"`
+}
+
+// Item Describes the operations available on a single path.
+type Item struct {
+	Ref     string     `json:"$ref,omitempty"`
+	Get     *Operation `json:"get,omitempty"`
+	Put     *Operation `json:"put,omitempty"`
+	Post    *Operation `json:"post,omitempty"`
+	Delete  *Operation `json:"delete,omitempty"`
+	Options *Operation `json:"options,omitempty"`
+	Head    *Operation `json:"head,omitempty"`
+	Patch   *Operation `json:"patch,omitempty"`
+}
+
+// Operation Describes a single API operation on a path.
+type Operation struct {
+	Tags        []string            `json:"tags,omitempty"`
+	Summary     string              `json:"summary,omitempty"`
+	Description string              `json:"description,omitempty"`
+	OperationID string              `json:"operationId,omitempty"`
+	Consumes    []string            `json:"consumes,omitempty"`
+	Produces    []string            `json:"produces,omitempty"`
+	Schemes     []string            `json:"schemes,omitempty"`
+	Parameters  []Parameter         `json:"parameters,omitempty"`
+	Responses   map[string]Response `json:"responses,omitempty"`
+	Deprecated  bool                `json:"deprecated,omitempty"`
+}
+
+// Parameter Describes a single operation parameter.
+type Parameter struct {
+	In          string `json:"in,omitempty"`
+	Name        string `json:"name,omitempty"`
+	Description string `json:"description,omitempty"`
+	Required    bool   `json:"required,omitempty"`
+	Schema      Schema `json:"schema,omitempty"`
+	Type        string `json:"type,omitempty"`
+	Format      string `json:"format,omitempty"`
+}
+
+// Schema Object allows the definition of input and output data types.
+type Schema struct {
+	Ref         string               `json:"$ref,omitempty"`
+	Title       string               `json:"title,omitempty"`
+	Format      string               `json:"format,omitempty"`
+	Description string               `json:"description,omitempty"`
+	Required    []string             `json:"required,omitempty"`
+	Type        string               `json:"type,omitempty"`
+	Properties  map[string]Propertie `json:"properties,omitempty"`
+}
+
+// Propertie are taken from the JSON Schema definition but their definitions were adjusted to the Swagger Specification
+type Propertie struct {
+	Title       string               `json:"title,omitempty"`
+	Description string               `json:"description,omitempty"`
+	Default     string               `json:"default,omitempty"`
+	Type        string               `json:"type,omitempty"`
+	Example     string               `json:"example,omitempty"`
+	Required    []string             `json:"required,omitempty"`
+	Format      string               `json:"format,omitempty"`
+	ReadOnly    bool                 `json:"readOnly,omitempty"`
+	Properties  map[string]Propertie `json:"properties,omitempty"`
+}
+
+// Response as they are returned from executing this operation.
+type Response struct {
+	Description string `json:"description,omitempty"`
+	Schema      Schema `json:"schema,omitempty"`
+	Ref         string `json:"$ref,omitempty"`
+}
+
+// Scurity Allows the definition of a security scheme that can be used by the operations
+type Scurity struct {
+	Type             string            `json:"type,omitempty"` // Valid values are "basic", "apiKey" or "oauth2".
+	Description      string            `json:"description,omitempty"`
+	Name             string            `json:"name,omitempty"`
+	In               string            `json:"in,omitempty"`   // Valid values are "query" or "header".
+	Flow             string            `json:"flow,omitempty"` // Valid values are "implicit", "password", "application" or "accessCode".
+	AuthorizationURL string            `json:"authorizationUrl,omitempty"`
+	TokenURL         string            `json:"tokenUrl,omitempty"`
+	Scopes           map[string]string `json:"scopes,omitempty"` // The available scopes for the OAuth2 security scheme.
+}
+
+// Tag Allows adding meta data to a single tag that is used by the Operation Object
+type Tag struct {
+	Name         string       `json:"name,omitempty"`
+	Description  string       `json:"description,omitempty"`
+	ExternalDocs ExternalDocs `json:"externalDocs,omitempty"`
+}
+
+// ExternalDocs include Additional external documentation
+type ExternalDocs struct {
+	Description string `json:"description,omitempty"`
+	URL         string `json:"url,omitempty"`
+}