Swagger documentation (TykTechnologies#2126)

See TykTechnologies/product#88

- [x] Definition of swagger models and responses
- [x] CI build step to validate the schema

.travis.yml

@@ -31,13 +31,22 @@ install:
   - go install ./...
     # As of 1.9, ./... no longer includes ./vendor/...
   - go install ./vendor/{golang.org/x/tools/cmd/goimports,github.com/wadey/gocovmerge,github.com/mattn/goveralls}
+  - go get github.com/go-swagger/go-swagger/cmd/swagger
 
 script:
   - sudo pip3 install google
   - sudo pip3 install protobuf
+    ### Needed to convert the swagger 2.0 file to openapi 3.0
+    ### The swagger docs are actually written as per the 2.0 spec as there is no
+    ### support for openapi 3.0 in Go - at least for now.
+    ### https://github.com/nodesource/distributions/blob/master/README.md#debinstall
+  - curl -sL https://deb.nodesource.com/setup_11.x | sudo -E bash -
+  - sudo -E apt-get -yq --no-install-suggests --no-install-recommends $(travis_apt_get_options) install nodejs
+  - sudo npm install -g api-spec-converter --unsafe-perm=true --allow-root
   - go build -tags 'coprocess python'
   - go build -tags 'coprocess lua'
   - go build -tags 'coprocess grpc'
+  - ./utils/ci-swagger.sh
   - ./utils/ci-test.sh
   - if [[ $LATEST_GO ]]; then goveralls -coverprofile=<(gocovmerge *.cov); fi
   - ./utils/ci-benchmark.sh

api.go

@@ -1,3 +1,28 @@
+// Tyk Gateway API
+//
+// The code below describes the Tyk Gateway API
+// Version: 2.8.0
+//
+//     Schemes: https, http
+//     Host: localhost
+//     BasePath: /tyk/
+//
+//     Consumes:
+//     - application/json
+//
+//     Produces:
+//     - application/json
+//
+//     Security:
+//     - api_key:
+//
+//     SecurityDefinitions:
+//     api_key:
+//          type: apiKey
+//          name: X-Tyk-Authorization
+//          in: header
+//
+// swagger:meta
 package main
 
 import (
@@ -28,16 +53,22 @@ import (
 )
 
 // apiModifyKeySuccess represents when a Key modification was successful
+//
+// swagger:model apiModifyKeySuccess
 type apiModifyKeySuccess struct {
+	// in:body
 	Key     string `json:"key"`
 	Status  string `json:"status"`
 	Action  string `json:"action"`
 	KeyHash string `json:"key_hash,omitempty"`
 }
 
 // apiStatusMessage represents an API status message
+//
+// swagger:model apiStatusMessage
 type apiStatusMessage struct {
-	Status  string `json:"status"`
+	Status string `json:"status"`
+	// Response details
 	Message string `json:"message"`
 }
 
@@ -448,6 +479,7 @@ func handleGetDetail(sessionKey, apiID string, byHash bool) (interface{}, int) {
 }
 
 // apiAllKeys represents a list of keys in the memory store
+// swagger:model
 type apiAllKeys struct {
 	APIKeys []string `json:"keys"`
 }
@@ -1101,6 +1133,7 @@ func groupResetHandler(w http.ResponseWriter, r *http.Request) {
 // was in the URL parameters, it will block until the reload is done.
 // Otherwise, it won't block and fn will be called once the reload is
 // finished.
+//
 func resetHandler(fn func()) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		var wg sync.WaitGroup
@@ -1255,6 +1288,8 @@ func createKeyHandler(w http.ResponseWriter, r *http.Request) {
 }
 
 // NewClientRequest is an outward facing JSON object translated from osin OAuthClients
+//
+// swagger:model NewClientRequest
 type NewClientRequest struct {
 	ClientID          string      `json:"client_id"`
 	ClientRedirectURI string      `json:"redirect_uri"`

apidef/api_definitions.go

@@ -330,6 +330,8 @@ type OpenIDOptions struct {
 }
 
 // APIDefinition represents the configuration for a single proxied API and it's versions.
+//
+// swagger:model
 type APIDefinition struct {
 	Id               bson.ObjectId `bson:"_id,omitempty" json:"id,omitempty"`
 	Name             string        `bson:"name" json:"name"`

oauth_manager.go

@@ -372,6 +372,7 @@ const (
 	prefixClientTokens = "oauth-client-tokens."
 )
 
+// swagger:model
 type OAuthClientToken struct {
 	Token   string `json:"code"`
 	Expires int64  `json:"expires"`

swagger.go

@@ -0,0 +1,25 @@
+package main
+
+import (
+	"github.com/TykTechnologies/tyk/apidef"
+	"github.com/TykTechnologies/tyk/user"
+)
+
+// parameterBodies
+// swagger:response parameterBodies
+type swaggerParameterBodies struct {
+	// in: body
+	APIStatusMessage apiStatusMessage
+	// in: body
+	APIModifyKeySuccess apiModifyKeySuccess
+	// in: body
+	NewClientRequest NewClientRequest
+	// in: body
+	APIDefinition apidef.APIDefinition
+	// in: body
+	SessionState user.SessionState
+	// in:body
+	APIAllKeys apiAllKeys
+	// in: body
+	OAuthClientToken OAuthClientToken
+}