From 51a8d212acf5d8841cf0e421e272b168b3a92f8e Mon Sep 17 00:00:00 2001 From: Lanre Adelowo Date: Fri, 3 May 2019 16:56:33 +0100 Subject: [PATCH] Swagger documentation (#2126) See https://github.com/TykTechnologies/product/issues/88 - [x] Definition of swagger models and responses - [x] CI build step to validate the schema --- .travis.yml | 9 + api.go | 37 +- apidef/api_definitions.go | 2 + oauth_manager.go | 1 + swagger.go | 25 + swagger.yml | 2373 +++++++++++++++++++++++++++++++++++++ tracing.go | 12 +- user/session.go | 2 + utils/ci-swagger.sh | 52 + 9 files changed, 2504 insertions(+), 9 deletions(-) create mode 100644 swagger.go create mode 100644 swagger.yml create mode 100755 utils/ci-swagger.sh diff --git a/.travis.yml b/.travis.yml index 903084dbb57..35ad5dd4161 100644 --- a/.travis.yml +++ b/.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 diff --git a/api.go b/api.go index 7f2ca58da9f..3051287c12d 100644 --- a/api.go +++ b/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,7 +53,10 @@ 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"` @@ -36,8 +64,11 @@ type apiModifyKeySuccess struct { } // 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"` diff --git a/apidef/api_definitions.go b/apidef/api_definitions.go index c88e4243c3a..44f66312030 100644 --- a/apidef/api_definitions.go +++ b/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"` diff --git a/oauth_manager.go b/oauth_manager.go index 2453c3cd87c..7d5f8ae29b3 100644 --- a/oauth_manager.go +++ b/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"` diff --git a/swagger.go b/swagger.go new file mode 100644 index 00000000000..844f0db9cbe --- /dev/null +++ b/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 +} diff --git a/swagger.yml b/swagger.yml new file mode 100644 index 00000000000..50e4e32660d --- /dev/null +++ b/swagger.yml @@ -0,0 +1,2373 @@ +openapi: 3.0.0 +info: + title: Tyk Gateway API + version: 2.8.0 + description: |- + The Tyk Gateway REST API is the primary means for integrating your application with the Tyk API Gateway system. This API is very small, and has no granular permissions system. It is intended to be used purely for internal automation and integration. + + **Warning: Under no circumstances should outside parties be granted access to this API.** + + The Tyk Gateway API is capable of: + + * Managing session objects (token generation) + * Managing and listing policies + * Managing and listing API Definitions (only when not using the Dashboard) + * Hot reloads / reloading a cluster configuration + * OAuth client creation (only when not using the Dashboard) + + In order to use the REST API, you울ll need to set the `secret` parameter in your tyk.conf file. + + The shared secret you set should then be sent along as a header with each REST API Request in order for it to be successful: + + ``` + x-tyk-authorization: + ``` +
+ The Tyk Gateway API is subsumed by the Tyk Dashboard API in Pro installations. +servers: + - url: 'http://localhost/tyk/' + - url: 'https://localhost/tyk/' +tags: + - name: Keys + description: |- + All keys that are used to access services via Tyk correspond to a session object that informs Tyk about the context of this particular token, like access rules and rate/quota allowance. + + Additionally see key session object data format. + - name: OAuth + description: |- + Manage oAuth clients, and manage their tokens + - name: Cache Invalidation + description: |- + Sometimes a cache might contain stale data, or it may just need to be cleared because of an invalid configuration. This call will purge all keys associated with a cache on an API-by-API basis. + - name: Hot Reload + description: + Force restart of the Gateway or whole cluster + - name: Health Checking + description: Check health check of the Gateway and loaded APIs + - name: Organisation Quotas + description: |- + It is possible to force API quota and rate limit across all keys that belong to a specific organisation ID. Rate limiting on an organisation level is useful for creating tiered access levels and trial accounts. + The Organisation rate limiting middleware works with both Quotas and Rate Limiters. In order to manage this functionality, a simple API has been put in place to manage these sessions. + Although the Organisation session-limiter uses the same session object, all other security keys are optional as they are not used. + +

Managing active status

+ To disallow access to an entire group of keys without rate limiting the organisation, create a session object with the "is_inactive" key set to true, this will block access before any other middleware is executed. This is useful when managing subscriptions for an organisation group and access needs to be blocked because of non-payment. + - name: Batch requests + description: |- + Tyk supports batch requests, so a client makes a single request to the API but gets a compound response object back. + + This is especially handy if clients have complex requests that have multiple synchronous dependencies and do not wish to have the entire request / response cycle running for each event. + + See detailed guide + - name: APIs + description: |- + **Note: Applies only to Tyk Gateway Community Edition** + + API Management is very simple using the Tyk REST API: each update only affects the underlying file, and this endpoint will only work with disk based installations, not Database-backed ones. + + API's that are added this way are flushed to to disk into the app_path folder using the format: `{api-id}.json`. Updating existing API's that use a different naming convention will cause those API's to be added, which could subsequently lead to a loading error and crash if they use the same listen_path. + + These methods only work on a single API node. If updating a cluster, it is important to ensure that all nodes are updated before initiating a reload. +paths: + /apis: + get: + description: |- + List APIs + Only if used without the Tyk Dashboard + tags: + - APIs + operationId: listApis + responses: + '200': + description: List of API definitions + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/APIDefinition' + example: + - name: "TestAPI" + use_keyless: true + active: true + proxy: + listen_path: "/test" + post: + description: |- + Create API + A single Tyk node can have its API Definitions queried, deleted and updated remotely. This functionality enables you to remotely update your Tyk definitions without having to manage the files manually. + tags: + - APIs + operationId: createApi + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/APIDefinition" + example: + name: "TestAPI" + use_keyless: true + active: true + proxy: + listen_path: "/test" + responses: + '200': + description: API created + content: + application/json: + schema: + $ref: "#/components/schemas/apiModifyKeySuccess" + example: + status: "ok" + action: "created" + key: "{...API JSON definition...}" + '400': + description: Malformed data + content: + application/json: + schema: + $ref: "#/components/schemas/apiStatusMessage" + example: + status: "error" + message: "Malformed API data" + '/apis/{apiID}': + parameters: + - description: The API ID + name: apiID + in: path + required: true + schema: + type: string + get: + description: |- + Get API definition + Only if used without the Tyk Dashboard + tags: + - APIs + operationId: getApi + responses: + '200': + description: API definition + content: + application/json: + schema: + $ref: "#/components/schemas/APIDefinition" + example: + name: "TestAPI" + use_keyless: true + active: true + proxy: + listen_path: "/test" + put: + description: | + Updating an API definition uses the same signature an object as a `POST`, however it will first ensure that the API ID that is being updated is the same as the one in the object being `PUT`. + + + Updating will completely replace the file descriptor and will not change an API Definition that has already been loaded, the hot-reload endpoint will need to be called to push the new definition to live. + tags: + - APIs + operationId: updateApi + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/APIDefinition" + example: + name: "TestAPI" + use_keyless: true + active: true + proxy: + listen_path: "/test" + responses: + '200': + description: API updated + content: + application/json: + schema: + $ref: "#/components/schemas/apiModifyKeySuccess" + example: + status: "ok" + action: "updated" + key: "{...API JSON definition...}" + '400': + description: Malformed data + content: + application/json: + schema: + $ref: "#/components/schemas/apiStatusMessage" + example: + status: "error" + message: "Malformed API data" + + delete: + description: |- + Deleting an API definition will remove the file from the file store, the API definition will NOT be unloaded, a separate reload request will need to be made to disable the API endpoint. + tags: + - APIs + operationId: deleteApi + responses: + '200': + description: API deleted + content: + application/json: + schema: + $ref: '#/components/schemas/apiStatusMessage' + example: + message: API deleted + status: ok + '400': + description: No API ID specified + content: + application/json: + schema: + $ref: '#/components/schemas/apiStatusMessage' + example: + message: API ID not specified + status: error + '/cache/{apiID}': + parameters: + - description: The API ID + name: apiID + in: path + required: true + schema: + type: string + delete: + summary: Invalidate cache + description: Invalidate cache for given API + tags: + - Cache Invalidation + operationId: invalidateCache + responses: + '200': + description: Invalidate cache + content: + application/json: + schema: + $ref: '#/components/schemas/apiStatusMessage' + example: + message: cache invalidated + status: ok + '/reload/': + get: + summary: Hot-reload a single node + description: Tyk is capable of reloading configurations without having to stop serving requests, this means that API configurations can be added at runtime, or even modified at runtime and those rules applied immediately without any downtime. + parameters: + - description: Block a response, until the reload is performed. This can be useful in scripting environments like CI/CD workflows. + name: block + in: query + required: false + schema: + type: boolean + enum: [true] + tags: + - Hot Reload + operationId: hotReload + responses: + '200': + description: Reload gateway + content: + application/json: + schema: + $ref: '#/components/schemas/apiStatusMessage' + example: + status: ok + '/reload/group': + get: + summary: Hot-reload a Tyk group + description: To reload a whole group of Tyk nodes (without using the Dashboard or host manager), you can send an API request to a single node, this node will then send a notification through the pub/sub infrastructure to all other listening nodes (including the host manager if it is being used to manage NginX) which will then trigger a global reload. + tags: + - Hot Reload + operationId: hotReloadGroup + responses: + '200': + description: Reload gateway + content: + application/json: + schema: + $ref: '#/components/schemas/apiStatusMessage' + example: + status: ok + '/hello': + get: + summary: Check the Health of the Gateway + description: Returns 200 response in case of success + tags: + - Health Checking + operationId: hello + responses: + '200': + description: Success + content: + text/html: + schema: + type: string + example: "Hello Tiki" + '/{listenPath}/hello': + parameters: + - in: path + name: listenPath + required: true + description: "Listen path of loaded API" + schema: + type: string + get: + summary: Check the Health of the API + description: Should point to API domain if it has own + tags: + - Health Checking + operationId: helloAPI + responses: + '200': + description: Success + content: + text/html: + schema: + type: string + example: "Hello Tiki" + /keys: + get: + summary: List Keys + description: You can retrieve all the keys in your Tyk instance. Returns an array of Key IDs. + tags: + - Keys + operationId: listKeys + responses: + '200': + description: List of all API keys + content: + application/json: + schema: + type: array + items: + type: string + post: + summary: Create a key + description: |- + Tyk will generate the access token based on the OrgID specified in the API Definition and a random UUID. This ensures that keys can be "owned" by different API Owners should segmentation be needed at an organisational level. +

+ API keys without access_rights data will be written to all APIs on the system (this also means that they will be created across all SessionHandlers and StorageHandlers, it is recommended to always embed access_rights data in a key to ensure that only targeted APIs and their back-ends are written to. + tags: + - Keys + operationId: addKey + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/SessionState" + example: + quota_max: 60 + quota_renews: 1406121006 + quota_renewal_rate: 60 + allowance: 100 + rate: 100 + per: 5 + org_id: 53ac07777cbb8c2d53000002 + responses: + '200': + description: New Key added + content: + application/json: + schema: + $ref: '#/components/schemas/apiModifyKeySuccess' + example: + action: created + key: '{...KEY JSON definition...}' + status: ok + '400': + description: Malformed data + content: + application/json: + schema: + $ref: '#/components/schemas/apiStatusMessage' + example: + message: Malformed Key data + status: error + '/keys/{keyID}': + parameters: + - description: The Key ID + name: keyID + in: path + required: true + schema: + type: string + get: + summary: Get a Key + description: Get session info about specified key. Should return up to date rate limit and quota usage numbers. + tags: + - Keys + operationId: getKey + responses: + '200': + description: Key object + content: + application/json: + schema: + $ref: '#/components/schemas/SessionState' + example: + quota_max: 60 + quota_renews: 1406121006 + quota_renewal_rate: 60 + allowance: 100 + rate: 100 + per: 5 + org_id: 53ac07777cbb8c2d53000002 + put: + summary: Update Key or Add custom Key + description: |- + You can also manually add keys to Tyk using your own key-generation algorithm. It is recommended if using this approach to ensure that the OrgID being used in the API Definition and the key data is blank so that Tyk does not try to prepend or manage the key in any way. + tags: + - Keys + operationId: updateKey + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/SessionState" + example: + quota_max: 60 + quota_renews: 1406121006 + quota_renewal_rate: 60 + allowance: 100 + rate: 100 + per: 5 + org_id: 53ac07777cbb8c2d53000002 + parameters: + - description: |- + Adding the suppress_reset parameter and setting it to 1, will cause Tyk to not reset the quota limit that is in the current live quota manager. By default Tyk will reset the quota in the live quota manager (initialising it) when adding a key. Adding the `suppress_reset` flag to the URL parameters will avoid this behaviour. + name: suppress_reset + in: query + required: false + schema: + type: string + enum: ["1"] + responses: + '200': + description: Key updated + content: + application/json: + schema: + $ref: '#/components/schemas/apiModifyKeySuccess' + example: + action: updated + status: ok + '400': + description: No or incorrect Key ID specified + content: + application/json: + schema: + $ref: '#/components/schemas/apiStatusMessage' + example: + message: Key ID not specified + status: error + delete: + summary: Delete Key + description: Deleting a key will remove it permanently from the system, however analytics relating to that key will still be available. + tags: + - Keys + operationId: deleteKey + responses: + '200': + description: Key deleted + content: + application/json: + schema: + $ref: '#/components/schemas/apiStatusMessage' + example: + action: Key deleted + status: ok + /oauth/clients/create: + post: + summary: Create new OAuth client + description: Any oAuth keys must be generated with the help of a client ID. These need to be pre-registered with Tyk before they can be used (in a similar vein to how you would register your app with Twitter before attempting to ask user permissions using their API). +

+

Creating OAuth clients with Access to Multiple APIs

+ New for Tyk Gateway 2.6.0 is the ability to create OAuth clients with access to more than one API. If you provide the api_id it works the same as in previous releases. If you don울t provide the api_id the request uses policy access rights and enumerates APIs from their setting in the newly created OAuth-client. + + + tags: + - OAuth + operationId: createOAuthClient + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/NewClientRequest" + example: + client_id: test + api_id: id + policy_id: policy + responses: + '200': + description: Client created + content: + application/json: + schema: + $ref: '#/components/schemas/NewClientRequest' + example: + client_id: test + api_id: id + policy_id: policy + '/oauth/clients/{apiID}': + get: + summary: List oAuth clients + description: oAuth Clients are organised by API ID, and therefore are queried as such. + tags: + - OAuth + operationId: listOAuthClients + parameters: + - description: The API ID + name: apiID + in: path + required: true + schema: + type: string + responses: + '200': + description: Get OAuth client details or a list of OAuth clients + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/NewClientRequest' + '/oauth/clients/{apiID}/{keyName}': + get: + summary: Get oAuth client + tags: + - OAuth + operationId: getOAuthClient + parameters: + - description: The API ID + name: apiID + in: path + required: true + schema: + type: string + minimum: 1 + - description: The Client ID + name: keyName + in: path + required: true + schema: + type: string + responses: + '200': + description: Get OAuth client details or a list of OAuth clients + content: + application/json: + schema: + $ref: '#/components/schemas/NewClientRequest' + example: + client_id: test + api_id: id + policy_id: policy + delete: + summary: Delete oAuth client + description: Please note that tokens issued with the client ID will still be valid until they expire. + tags: + - OAuth + operationId: deleteOAuthClient + parameters: + - description: The API ID + name: apiID + in: path + required: true + schema: + type: string + minimum: 1 + - description: The Client ID + name: keyName + in: path + required: true + schema: + type: string + responses: + '200': + description: OAuth client deleted + content: + application/json: + schema: + $ref: '#/components/schemas/apiModifyKeySuccess' + example: + action: deleted + status: ok + '/oauth/clients/{apiID}/{keyName}/tokens': + get: + summary: List tokens + description: This endpoint allows you to retrieve a list of all current tokens and their expiry date for a provided API ID and OAuth-client ID in the following format. This endpoint will work only for newly created tokens. +
+
+ You can control how long you want to store expired tokens in this list using `oauth_token_expired_retain_period` gateway option, which specifies retain period for expired tokens stored in Redis. By default expired token not get removed. See here for more details. + tags: + - OAuth + operationId: getOAuthClientTokens + parameters: + - description: The API ID + name: apiID + in: path + required: true + schema: + type: string + minimum: 1 + - description: The Client ID + name: keyName + in: path + required: true + schema: + type: string + responses: + '200': + description: Get a list of tokens + content: + application/json: + schema: + type: array + items: + type: string + example: + - "tok1" + - "tok2" + '/oauth/refresh/{keyName}': + delete: + summary: Invalidate OAuth refresh token + description: It is possible to invalidate refresh tokens in order to manage OAuth client access more robustly. + tags: + - OAuth + operationId: invalidateOAuthRefresh + parameters: + - description: The API id + name: api_id + in: query + required: true + schema: + type: string + - description: Refresh token + name: keyName + in: path + required: true + schema: + type: string + responses: + '200': + description: Deleted + content: + application/json: + schema: + $ref: '#/components/schemas/apiModifyKeySuccess' + '/oauth/authorize-client/': + post: + description: With the OAuth flow you will need to create authorisation or access tokens for your clients, in order to do this, Tyk provides a private API endpoint for your application to generate these codes and redirect the end-user back to the API Client. + summary: Authorize client + requestBody: + required: true + content: + application/x-www-form-urlencoded: + schema: + type: object + properties: + response_type: + description: Should be provided by requesting client as part of authorisation request, this should be either `code` or `token` depending on the methods you have specified for the API. + type: string + client_id: + description: Should be provided by requesting client as part of authorisation request. The Client ID that is making the request. + type: string + redirect_uri: + description: Should be provided by requesting client as part of authorisation request. Must match with the record stored with Tyk. + type: string + key_rules: + description: A string representation of a Session Object (form-encoded). This should be provided by your application in order to apply any quotas or rules to the key. + type: string + example: + response_type: code + client_id: 21e2baf424674f6461faca6d45285bbb + redirect_uri: http%3A%2F%2Foauth.com%2Fredirect + key_rules: '%7B+++++%22allowance%22%3A+999%2C+++++%22rate%22%3A+1000%2C+++++%22per%22%3A+60%2C+++++%22expires%22%3A+0%2C+++++%22quota_max%22%3A+-1%2C+++++%22quota_renews%22%3A+1406121006%2C+++++%22quota_remaining%22%3A+0%2C+++++%22quota_renewal_rate%22%3A+60%2C+++++%22access_rights%22%3A+%7B+++++++++%22528a67c1ac9940964f9a41ae79235fcc%22%3A+%7B+++++++++++++%22api_name%22%3A+%22OAuth+Test+API%22%2C+++++++++++++%22api_id%22%3A+%22528a67c1ac9940964f9a41ae79235fcc%22%2C+++++++++++++%22versions%22%3A+%5B+++++++++++++++++%22Default%22+++++++++++++%5D+++++++++%7D+++++%7D%2C+++++%22org_id%22%3A+%2253ac07777cbb8c2d53000002%22+%7D' + tags: + - OAuth + operationId: authorizeClient + responses: + '200': + description: Succesful response + content: + application/json: + schema: + type: object + example: + code: MWY0ZDRkMzktOTYwNi00NDRiLTk2YmQtOWQxOGQ3Mjc5Yzdk + redirect_to: 'http://client-app.com/oauth-redirect/?code=MWY0ZDRkMzktOTYwNi00NDRiLTk2YmQtOWQxOGQ3Mjc5Yzdk' + /orgs/keys: + get: + summary: List Organisation Keys + description: |- + You can now set rate limits at the organisation level by using the following fields - allowance and rate. These are the number of allowed requests for the specified per value, and need to be set to the same value. If you don울t want to have organisation level rate limiting, set 욱rate우 or 욱per우 to zero, or don울t add them to your request. + tags: + - Organisation Quotas + operationId: listOrgKeys + responses: + '200': + description: List of all API keys + content: + application/json: + schema: + type: object + properties: + keys: + type: array + items: + type: string + example: + keys: + - "key1" + - "key2" + post: + summary: Create an organisation key + description: |- + This work similar to Keys API except that Key ID is always equals Organisation ID + tags: + - Organisation Quotas + operationId: addOrgKey + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/SessionState" + example: + quota_max: 60 + quota_renews: 1406121006 + quota_renewal_rate: 60 + allowance: 100 + rate: 100 + per: 5 + org_id: 53ac07777cbb8c2d53000002 + responses: + '200': + description: New Key added + content: + application/json: + schema: + $ref: '#/components/schemas/apiModifyKeySuccess' + example: + action: created + key: '{...KEY JSON definition...}' + status: ok + '/orgs/keys/{keyID}': + parameters: + - description: The Key ID + name: keyID + in: path + required: true + schema: + type: string + get: + summary: Get an Organisation Key + description: Get session info about specified orgnanisation key. Should return up to date rate limit and quota usage numbers. + tags: + - Organisation Quotas + operationId: getOrgKey + responses: + '200': + description: Key object + content: + application/json: + schema: + $ref: '#/components/schemas/SessionState' + put: + summary: Update Organisation Key + description: |- + This work similar to Keys API except that Key ID is always equals Organisation ID + + For Gateway v2.6.0 onwards, you can now set rate limits at the organisation level by using the following fields - allowance and rate. These are the number of allowed requests for the specified per value, and need to be set to the same value. If you don울t want to have organisation level rate limiting, set `rate` or `per` to zero, or don울t add them to your request. + tags: + - Organisation Quotas + operationId: updateOrgKey + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/SessionState" + example: + quota_max: 60 + quota_renews: 1406121006 + quota_renewal_rate: 60 + allowance: 100 + rate: 100 + per: 5 + org_id: 53ac07777cbb8c2d53000002 + parameters: + - description: |- + Adding the `reset_quota` parameter and setting it to 1, will cause Tyk reset the organisations quota in the live quota manager, it is recommended to use this mechanism to reset organisation-level access if a monthly subscription is in place. + name: reset_quota + in: query + required: false + schema: + type: string + enum: ["1"] + responses: + '200': + description: Key updated + content: + application/json: + schema: + $ref: '#/components/schemas/apiModifyKeySuccess' + example: + action: updated + status: ok + delete: + summary: Delete Organisation Key + description: Deleting a key will remove all limits from organisation. It does not affects regualar keys created within organisation. + tags: + - Organisation Quotas + operationId: deleteOrgKey + responses: + '200': + description: Key deleted + content: + application/json: + schema: + $ref: '#/components/schemas/apiStatusMessage' + example: + action: Key deleted + status: ok + /{listen_path}/tyk/batch: + parameters: + - name: listen_path + in: path + required: true + description: "API listen path" + schema: + type: string + post: + summary: Run batch request + tags: + - Batch requests + operationId: batch + responses: + '200': + $ref: '#/components/schemas/apiStatusMessage' +components: + responses: + parameterBodies: + content: + application/json: + schema: + $ref: '#/components/schemas/OAuthClientToken' + description: parameterBodies + schemas: + APIDefinition: + properties: + tags: + items: + type: string + type: array + x-go-name: Tags + CORS: + properties: + allow_credentials: + type: boolean + x-go-name: AllowCredentials + allowed_headers: + items: + type: string + type: array + x-go-name: AllowedHeaders + allowed_methods: + items: + type: string + type: array + x-go-name: AllowedMethods + allowed_origins: + items: + type: string + type: array + x-go-name: AllowedOrigins + debug: + type: boolean + x-go-name: Debug + enable: + type: boolean + x-go-name: Enable + exposed_headers: + items: + type: string + type: array + x-go-name: ExposedHeaders + max_age: + format: int64 + type: integer + x-go-name: MaxAge + options_passthrough: + type: boolean + x-go-name: OptionsPassthrough + type: object + active: + type: boolean + x-go-name: Active + allowed_ips: + items: + type: string + type: array + x-go-name: AllowedIPs + api_id: + type: string + x-go-name: APIID + auth: + $ref: '#/components/schemas/Auth' + auth_provider: + $ref: '#/components/schemas/AuthProviderMeta' + base_identity_provided_by: + $ref: '#/components/schemas/AuthTypeEnum' + basic_auth: + properties: + body_password_regexp: + type: string + x-go-name: BodyPasswordRegexp + body_user_regexp: + type: string + x-go-name: BodyUserRegexp + cache_ttl: + format: int64 + type: integer + x-go-name: CacheTTL + disable_caching: + type: boolean + x-go-name: DisableCaching + extract_from_body: + type: boolean + x-go-name: ExtractFromBody + type: object + x-go-name: BasicAuth + blacklisted_ips: + items: + type: string + type: array + x-go-name: BlacklistedIPs + cache_options: + $ref: '#/components/schemas/CacheOptions' + certificates: + items: + type: string + type: array + x-go-name: Certificates + client_certificates: + items: + type: string + type: array + x-go-name: ClientCertificates + config_data: + additionalProperties: + type: object + type: object + x-go-name: ConfigData + custom_middleware: + $ref: '#/components/schemas/MiddlewareSection' + custom_middleware_bundle: + type: string + x-go-name: CustomMiddlewareBundle + definition: + properties: + key: + type: string + x-go-name: Key + location: + type: string + x-go-name: Location + strip_path: + type: boolean + x-go-name: StripPath + type: object + x-go-name: VersionDefinition + disable_quota: + type: boolean + x-go-name: DisableQuota + disable_rate_limit: + type: boolean + x-go-name: DisableRateLimit + do_not_track: + type: boolean + x-go-name: DoNotTrack + domain: + type: string + x-go-name: Domain + dont_set_quota_on_create: + type: boolean + x-go-name: DontSetQuotasOnCreate + enable_batch_request_support: + type: boolean + x-go-name: EnableBatchRequestSupport + enable_context_vars: + type: boolean + x-go-name: EnableContextVars + enable_coprocess_auth: + type: boolean + x-go-name: EnableCoProcessAuth + enable_ip_blacklisting: + type: boolean + x-go-name: EnableIpBlacklisting + enable_ip_whitelisting: + type: boolean + x-go-name: EnableIpWhiteListing + enable_jwt: + type: boolean + x-go-name: EnableJWT + enable_signature_checking: + type: boolean + x-go-name: EnableSignatureChecking + event_handlers: + $ref: '#/components/schemas/EventHandlerMetaConfig' + expire_analytics_after: + format: int64 + type: integer + x-go-name: ExpireAnalyticsAfter + global_rate_limit: + $ref: '#/components/schemas/GlobalRateLimit' + hmac_allowed_algorithms: + items: + type: string + type: array + x-go-name: HmacAllowedAlgorithms + hmac_allowed_clock_skew: + format: double + type: number + x-go-name: HmacAllowedClockSkew + id: + $ref: '#/components/schemas/ObjectId' + internal: + type: boolean + x-go-name: Internal + jwt_client_base_field: + type: string + x-go-name: JWTClientIDBaseField + jwt_expires_at_validation_skew: + format: uint64 + type: integer + x-go-name: JWTExpiresAtValidationSkew + jwt_identity_base_field: + type: string + x-go-name: JWTIdentityBaseField + jwt_issued_at_validation_skew: + format: uint64 + type: integer + x-go-name: JWTIssuedAtValidationSkew + jwt_not_before_validation_skew: + format: uint64 + type: integer + x-go-name: JWTNotBeforeValidationSkew + jwt_policy_field_name: + type: string + x-go-name: JWTPolicyFieldName + jwt_scope_claim_name: + type: string + x-go-name: JWTScopeClaimName + jwt_scope_to_policy_mapping: + additionalProperties: + type: string + type: object + x-go-name: JWTScopeToPolicyMapping + jwt_signing_method: + type: string + x-go-name: JWTSigningMethod + jwt_skip_kid: + type: boolean + x-go-name: JWTSkipKid + jwt_source: + type: string + x-go-name: JWTSource + name: + type: string + x-go-name: Name + notifications: + $ref: '#/components/schemas/NotificationsManager' + oauth_meta: + properties: + allowed_access_types: + items: + $ref: '#/components/schemas/AccessRequestType' + type: array + x-go-name: AllowedAccessTypes + allowed_authorize_types: + items: + $ref: '#/components/schemas/AuthorizeRequestType' + type: array + x-go-name: AllowedAuthorizeTypes + auth_login_redirect: + type: string + x-go-name: AuthorizeLoginRedirect + type: object + x-go-name: Oauth2Meta + openid_options: + $ref: '#/components/schemas/OpenIDOptions' + org_id: + type: string + x-go-name: OrgID + pinned_public_keys: + additionalProperties: + type: string + type: object + x-go-name: PinnedPublicKeys + proxy: + properties: + check_host_against_uptime_tests: + type: boolean + x-go-name: CheckHostAgainstUptimeTests + disable_strip_slash: + type: boolean + x-go-name: DisableStripSlash + enable_load_balancing: + type: boolean + x-go-name: EnableLoadBalancing + listen_path: + type: string + x-go-name: ListenPath + preserve_host_header: + type: boolean + x-go-name: PreserveHostHeader + service_discovery: + $ref: '#/components/schemas/ServiceDiscoveryConfiguration' + strip_listen_path: + type: boolean + x-go-name: StripListenPath + target_list: + items: + type: string + type: array + x-go-name: Targets + target_url: + type: string + x-go-name: TargetURL + transport: + properties: + proxy_url: + type: string + x-go-name: ProxyURL + ssl_ciphers: + items: + type: string + type: array + x-go-name: SSLCipherSuites + ssl_insecure_skip_verify: + type: boolean + x-go-name: SSLInsecureSkipVerify + ssl_min_version: + format: uint16 + type: integer + x-go-name: SSLMinVersion + type: object + x-go-name: Transport + type: object + x-go-name: Proxy + response_processors: + items: + $ref: '#/components/schemas/ResponseProcessor' + type: array + x-go-name: ResponseProcessors + session_lifetime: + format: int64 + type: integer + x-go-name: SessionLifetime + session_provider: + $ref: '#/components/schemas/SessionProviderMeta' + slug: + type: string + x-go-name: Slug + strip_auth_data: + type: boolean + x-go-name: StripAuthData + tag_headers: + items: + type: string + type: array + x-go-name: TagHeaders + upstream_certificates: + additionalProperties: + type: string + type: object + x-go-name: UpstreamCertificates + uptime_tests: + properties: + check_list: + items: + $ref: '#/components/schemas/HostCheckObject' + type: array + x-go-name: CheckList + config: + properties: + expire_utime_after: + format: int64 + type: integer + x-go-name: ExpireUptimeAnalyticsAfter + recheck_wait: + format: int64 + type: integer + x-go-name: RecheckWait + service_discovery: + $ref: '#/components/schemas/ServiceDiscoveryConfiguration' + type: object + x-go-name: Config + type: object + x-go-name: UptimeTests + use_basic_auth: + type: boolean + x-go-name: UseBasicAuth + use_keyless: + type: boolean + x-go-name: UseKeylessAccess + use_mutual_tls_auth: + type: boolean + x-go-name: UseMutualTLSAuth + use_oauth2: + type: boolean + x-go-name: UseOauth2 + use_openid: + type: boolean + x-go-name: UseOpenID + use_standard_auth: + type: boolean + x-go-name: UseStandardAuth + version_data: + properties: + default_version: + type: string + x-go-name: DefaultVersion + not_versioned: + type: boolean + x-go-name: NotVersioned + versions: + additionalProperties: + $ref: '#/components/schemas/VersionInfo' + type: object + x-go-name: Versions + type: object + x-go-name: VersionData + title: >- + APIDefinition represents the configuration for a single proxied API and + it's versions. + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + APILimit: + description: APILimit stores quota and rate limit on ACL level (per API) + properties: + per: + format: double + type: number + x-go-name: Per + quota_max: + format: int64 + type: integer + x-go-name: QuotaMax + quota_remaining: + format: int64 + type: integer + x-go-name: QuotaRemaining + quota_renewal_rate: + format: int64 + type: integer + x-go-name: QuotaRenewalRate + quota_renews: + format: int64 + type: integer + x-go-name: QuotaRenews + rate: + format: double + type: number + x-go-name: Rate + set_by_policy: + type: boolean + x-go-name: SetByPolicy + throttle_interval: + format: double + type: number + x-go-name: ThrottleInterval + throttle_retry_limit: + format: int64 + type: integer + x-go-name: ThrottleRetryLimit + type: object + x-go-package: github.com/TykTechnologies/tyk/user + AccessDefinition: + description: AccessDefinition defines which versions of an API a key has access to + properties: + allowed_urls: + items: + $ref: '#/components/schemas/AccessSpec' + type: array + x-go-name: AllowedURLs + api_id: + type: string + x-go-name: APIID + api_name: + type: string + x-go-name: APIName + limit: + $ref: '#/components/schemas/APILimit' + versions: + items: + type: string + type: array + x-go-name: Versions + type: object + x-go-package: github.com/TykTechnologies/tyk/user + AccessRequestType: + description: AccessRequestType is the type for OAuth param `grant_type` + type: string + x-go-package: github.com/TykTechnologies/tyk/vendor/github.com/lonelycode/osin + AccessSpec: + description: >- + AccessSpecs define what URLS a user has access to an what methods are + enabled + properties: + methods: + items: + type: string + type: array + x-go-name: Methods + url: + type: string + x-go-name: URL + type: object + x-go-package: github.com/TykTechnologies/tyk/user + Auth: + properties: + auth_header_name: + type: string + x-go-name: AuthHeaderName + cookie_name: + type: string + x-go-name: CookieName + param_name: + type: string + x-go-name: ParamName + signature: + $ref: '#/components/schemas/SignatureConfig' + use_certificate: + type: boolean + x-go-name: UseCertificate + use_cookie: + type: boolean + x-go-name: UseCookie + use_param: + type: boolean + x-go-name: UseParam + validate_signature: + type: boolean + x-go-name: ValidateSignature + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + AuthProviderCode: + type: string + x-go-package: github.com/TykTechnologies/tyk/apidef + AuthProviderMeta: + properties: + meta: + additionalProperties: + type: object + type: object + x-go-name: Meta + name: + $ref: '#/components/schemas/AuthProviderCode' + storage_engine: + $ref: '#/components/schemas/StorageEngineCode' + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + AuthTypeEnum: + type: string + x-go-package: github.com/TykTechnologies/tyk/apidef + AuthorizeRequestType: + description: AuthorizeRequestType is the type for OAuth param `response_type` + type: string + x-go-package: github.com/TykTechnologies/tyk/vendor/github.com/lonelycode/osin + CacheMeta: + properties: + cache_key_regex: + type: string + x-go-name: CacheKeyRegex + method: + type: string + x-go-name: Method + path: + type: string + x-go-name: Path + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + CacheOptions: + properties: + cache_all_safe_requests: + type: boolean + x-go-name: CacheAllSafeRequests + cache_control_ttl_header: + type: string + x-go-name: CacheControlTTLHeader + cache_response_codes: + items: + format: int64 + type: integer + type: array + x-go-name: CacheOnlyResponseCodes + cache_timeout: + format: int64 + type: integer + x-go-name: CacheTimeout + enable_cache: + type: boolean + x-go-name: EnableCache + enable_upstream_cache_control: + type: boolean + x-go-name: EnableUpstreamCacheControl + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + CircuitBreakerMeta: + properties: + method: + type: string + x-go-name: Method + path: + type: string + x-go-name: Path + return_to_service_after: + format: int64 + type: integer + x-go-name: ReturnToServiceAfter + samples: + format: int64 + type: integer + x-go-name: Samples + threshold_percent: + format: double + type: number + x-go-name: ThresholdPercent + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + EndPointMeta: + properties: + method_actions: + additionalProperties: + $ref: '#/components/schemas/EndpointMethodMeta' + type: object + x-go-name: MethodActions + path: + type: string + x-go-name: Path + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + EndpointMethodAction: + type: string + x-go-package: github.com/TykTechnologies/tyk/apidef + EndpointMethodMeta: + properties: + action: + $ref: '#/components/schemas/EndpointMethodAction' + code: + format: int64 + type: integer + x-go-name: Code + data: + type: string + x-go-name: Data + headers: + additionalProperties: + type: string + type: object + x-go-name: Headers + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + EventHandlerMetaConfig: + properties: + events: + x-go-name: Events + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + ExtendedPathsSet: + properties: + advance_cache_config: + items: + $ref: '#/components/schemas/CacheMeta' + type: array + x-go-name: AdvanceCacheConfig + black_list: + items: + $ref: '#/components/schemas/EndPointMeta' + type: array + x-go-name: BlackList + cache: + items: + type: string + type: array + x-go-name: Cached + circuit_breakers: + items: + $ref: '#/components/schemas/CircuitBreakerMeta' + type: array + x-go-name: CircuitBreaker + do_not_track_endpoints: + items: + $ref: '#/components/schemas/TrackEndpointMeta' + type: array + x-go-name: DoNotTrackEndpoints + hard_timeouts: + items: + $ref: '#/components/schemas/HardTimeoutMeta' + type: array + x-go-name: HardTimeouts + ignored: + items: + $ref: '#/components/schemas/EndPointMeta' + type: array + x-go-name: Ignored + internal: + items: + $ref: '#/components/schemas/InternalMeta' + type: array + x-go-name: Internal + method_transforms: + items: + $ref: '#/components/schemas/MethodTransformMeta' + type: array + x-go-name: MethodTransforms + size_limits: + items: + $ref: '#/components/schemas/RequestSizeMeta' + type: array + x-go-name: SizeLimit + track_endpoints: + items: + $ref: '#/components/schemas/TrackEndpointMeta' + type: array + x-go-name: TrackEndpoints + transform: + items: + $ref: '#/components/schemas/TemplateMeta' + type: array + x-go-name: Transform + transform_headers: + items: + $ref: '#/components/schemas/HeaderInjectionMeta' + type: array + x-go-name: TransformHeader + transform_jq: + items: + $ref: '#/components/schemas/TransformJQMeta' + type: array + x-go-name: TransformJQ + transform_jq_response: + items: + $ref: '#/components/schemas/TransformJQMeta' + type: array + x-go-name: TransformJQResponse + transform_response: + items: + $ref: '#/components/schemas/TemplateMeta' + type: array + x-go-name: TransformResponse + transform_response_headers: + items: + $ref: '#/components/schemas/HeaderInjectionMeta' + type: array + x-go-name: TransformResponseHeader + url_rewrites: + items: + $ref: '#/components/schemas/URLRewriteMeta' + type: array + x-go-name: URLRewrite + validate_json: + items: + $ref: '#/components/schemas/ValidatePathMeta' + type: array + x-go-name: ValidateJSON + virtual: + items: + $ref: '#/components/schemas/VirtualMeta' + type: array + x-go-name: Virtual + white_list: + items: + $ref: '#/components/schemas/EndPointMeta' + type: array + x-go-name: WhiteList + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + GlobalRateLimit: + properties: + per: + format: double + type: number + x-go-name: Per + rate: + format: double + type: number + x-go-name: Rate + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + HardTimeoutMeta: + properties: + method: + type: string + x-go-name: Method + path: + type: string + x-go-name: Path + timeout: + format: int64 + type: integer + x-go-name: TimeOut + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + HashType: + type: string + x-go-package: github.com/TykTechnologies/tyk/user + HeaderInjectionMeta: + properties: + act_on: + type: boolean + x-go-name: ActOnResponse + add_headers: + additionalProperties: + type: string + type: object + x-go-name: AddHeaders + delete_headers: + items: + type: string + type: array + x-go-name: DeleteHeaders + method: + type: string + x-go-name: Method + path: + type: string + x-go-name: Path + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + HostCheckObject: + properties: + body: + type: string + x-go-name: Body + headers: + additionalProperties: + type: string + type: object + x-go-name: Headers + method: + type: string + x-go-name: Method + url: + type: string + x-go-name: CheckURL + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + IdExtractorSource: + type: string + x-go-package: github.com/TykTechnologies/tyk/apidef + IdExtractorType: + type: string + x-go-package: github.com/TykTechnologies/tyk/apidef + InternalMeta: + properties: + method: + type: string + x-go-name: Method + path: + type: string + x-go-name: Path + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + MethodTransformMeta: + properties: + method: + type: string + x-go-name: Method + path: + type: string + x-go-name: Path + to_method: + type: string + x-go-name: ToMethod + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + MiddlewareDefinition: + properties: + name: + type: string + x-go-name: Name + path: + type: string + x-go-name: Path + require_session: + type: boolean + x-go-name: RequireSession + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + MiddlewareDriver: + type: string + x-go-package: github.com/TykTechnologies/tyk/apidef + MiddlewareIdExtractor: + properties: + extract_from: + $ref: '#/components/schemas/IdExtractorSource' + extract_with: + $ref: '#/components/schemas/IdExtractorType' + extractor_config: + additionalProperties: + type: object + type: object + x-go-name: ExtractorConfig + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + MiddlewareSection: + properties: + auth_check: + $ref: '#/components/schemas/MiddlewareDefinition' + driver: + $ref: '#/components/schemas/MiddlewareDriver' + id_extractor: + $ref: '#/components/schemas/MiddlewareIdExtractor' + post: + items: + $ref: '#/components/schemas/MiddlewareDefinition' + type: array + x-go-name: Post + post_key_auth: + items: + $ref: '#/components/schemas/MiddlewareDefinition' + type: array + x-go-name: PostKeyAuth + pre: + items: + $ref: '#/components/schemas/MiddlewareDefinition' + type: array + x-go-name: Pre + response: + items: + $ref: '#/components/schemas/MiddlewareDefinition' + type: array + x-go-name: Response + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + NewClientRequest: + description: >- + NewClientRequest is an outward facing JSON object translated from osin + OAuthClients + properties: + api_id: + type: string + x-go-name: APIID + client_id: + type: string + x-go-name: ClientID + description: + type: string + x-go-name: Description + meta_data: + type: object + x-go-name: MetaData + policy_id: + type: string + x-go-name: PolicyID + redirect_uri: + type: string + x-go-name: ClientRedirectURI + secret: + type: string + x-go-name: ClientSecret + type: object + x-go-package: github.com/TykTechnologies/tyk + NotificationsManager: + description: 'TODO: Make this more generic' + properties: + oauth_on_keychange_url: + type: string + x-go-name: OAuthKeyChangeURL + shared_secret: + type: string + x-go-name: SharedSecret + title: >- + NotificationsManager handles sending notifications to OAuth endpoints to + notify the provider of key changes. + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + OAuthClientToken: + properties: + code: + type: string + x-go-name: Token + expires: + format: int64 + type: integer + x-go-name: Expires + type: object + x-go-package: github.com/TykTechnologies/tyk + OIDProviderConfig: + properties: + client_ids: + additionalProperties: + type: string + type: object + x-go-name: ClientIDs + issuer: + type: string + x-go-name: Issuer + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + ObjectId: + description: 'http://www.mongodb.org/display/DOCS/Object+IDs' + title: >- + ObjectId is a unique ID identifying a BSON value. It must be exactly 12 + bytes + + long. MongoDB objects by default have such a property set in their "_id" + + property. + type: string + x-go-package: github.com/TykTechnologies/tyk/vendor/gopkg.in/mgo.v2/bson + OpenIDOptions: + properties: + providers: + items: + $ref: '#/components/schemas/OIDProviderConfig' + type: array + x-go-name: Providers + segregate_by_client: + type: boolean + x-go-name: SegregateByClient + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + Regexp: + description: Regexp is a wrapper around regexp.Regexp but with caching + properties: + FromCache: + type: boolean + type: object + x-go-package: github.com/TykTechnologies/tyk/regexp + RequestInputType: + type: string + x-go-package: github.com/TykTechnologies/tyk/apidef + RequestSizeMeta: + properties: + method: + type: string + x-go-name: Method + path: + type: string + x-go-name: Path + size_limit: + format: int64 + type: integer + x-go-name: SizeLimit + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + ResponseProcessor: + properties: + name: + type: string + x-go-name: Name + options: + type: object + x-go-name: Options + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + RoutingTrigger: + properties: + 'on': + $ref: '#/components/schemas/RoutingTriggerOnType' + options: + $ref: '#/components/schemas/RoutingTriggerOptions' + rewrite_to: + type: string + x-go-name: RewriteTo + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + RoutingTriggerOnType: + type: string + x-go-package: github.com/TykTechnologies/tyk/apidef + RoutingTriggerOptions: + properties: + header_matches: + additionalProperties: + $ref: '#/components/schemas/StringRegexMap' + type: object + x-go-name: HeaderMatches + path_part_matches: + additionalProperties: + $ref: '#/components/schemas/StringRegexMap' + type: object + x-go-name: PathPartMatches + payload_matches: + $ref: '#/components/schemas/StringRegexMap' + query_val_matches: + additionalProperties: + $ref: '#/components/schemas/StringRegexMap' + type: object + x-go-name: QueryValMatches + request_context_matches: + additionalProperties: + $ref: '#/components/schemas/StringRegexMap' + type: object + x-go-name: RequestContextMatches + session_meta_matches: + additionalProperties: + $ref: '#/components/schemas/StringRegexMap' + type: object + x-go-name: SessionMetaMatches + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + ServiceDiscoveryConfiguration: + properties: + cache_timeout: + format: int64 + type: integer + x-go-name: CacheTimeout + data_path: + type: string + x-go-name: DataPath + endpoint_returns_list: + type: boolean + x-go-name: EndpointReturnsList + parent_data_path: + type: string + x-go-name: ParentDataPath + port_data_path: + type: string + x-go-name: PortDataPath + query_endpoint: + type: string + x-go-name: QueryEndpoint + target_path: + type: string + x-go-name: TargetPath + use_discovery_service: + type: boolean + x-go-name: UseDiscoveryService + use_nested_query: + type: boolean + x-go-name: UseNestedQuery + use_target_list: + type: boolean + x-go-name: UseTargetList + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + SessionProviderCode: + type: string + x-go-package: github.com/TykTechnologies/tyk/apidef + SessionProviderMeta: + properties: + meta: + additionalProperties: + type: object + type: object + x-go-name: Meta + name: + $ref: '#/components/schemas/SessionProviderCode' + storage_engine: + $ref: '#/components/schemas/StorageEngineCode' + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + SessionState: + description: >- + There's a data structure that's based on this and it's used for Protocol + Buffer support, make sure to update + "coprocess/proto/coprocess_session_state.proto" and generate the + bindings using: cd coprocess/proto && ./update_bindings.sh + properties: + tags: + items: + type: string + type: array + x-go-name: Tags + access_rights: + additionalProperties: + $ref: '#/components/schemas/AccessDefinition' + type: object + x-go-name: AccessRights + alias: + type: string + x-go-name: Alias + allowance: + format: double + type: number + x-go-name: Allowance + apply_policies: + items: + type: string + type: array + x-go-name: ApplyPolicies + apply_policy_id: + type: string + x-go-name: ApplyPolicyID + basic_auth_data: + properties: + hash_type: + $ref: '#/components/schemas/HashType' + password: + type: string + x-go-name: Password + type: object + x-go-name: BasicAuthData + certificate: + type: string + x-go-name: Certificate + data_expires: + format: int64 + type: integer + x-go-name: DataExpires + enable_detail_recording: + type: boolean + x-go-name: EnableDetailedRecording + expires: + format: int64 + type: integer + x-go-name: Expires + hmac_enabled: + type: boolean + x-go-name: HMACEnabled + hmac_string: + type: string + x-go-name: HmacSecret + id_extractor_deadline: + format: int64 + type: integer + x-go-name: IdExtractorDeadline + is_inactive: + type: boolean + x-go-name: IsInactive + jwt_data: + properties: + secret: + type: string + x-go-name: Secret + type: object + x-go-name: JWTData + last_check: + format: int64 + type: integer + x-go-name: LastCheck + last_updated: + type: string + x-go-name: LastUpdated + meta_data: + additionalProperties: + type: object + type: object + x-go-name: MetaData + monitor: + properties: + trigger_limits: + items: + format: double + type: number + type: array + x-go-name: TriggerLimits + type: object + x-go-name: Monitor + oauth_client_id: + type: string + x-go-name: OauthClientID + oauth_keys: + additionalProperties: + type: string + type: object + x-go-name: OauthKeys + org_id: + type: string + x-go-name: OrgID + per: + format: double + type: number + x-go-name: Per + quota_max: + format: int64 + type: integer + x-go-name: QuotaMax + quota_remaining: + format: int64 + type: integer + x-go-name: QuotaRemaining + quota_renewal_rate: + format: int64 + type: integer + x-go-name: QuotaRenewalRate + quota_renews: + format: int64 + type: integer + x-go-name: QuotaRenews + rate: + format: double + type: number + x-go-name: Rate + session_lifetime: + format: int64 + type: integer + x-go-name: SessionLifetime + throttle_interval: + format: double + type: number + x-go-name: ThrottleInterval + throttle_retry_limit: + format: int64 + type: integer + x-go-name: ThrottleRetryLimit + title: >- + SessionState objects represent a current API session, mainly used for + rate limiting. + type: object + x-go-package: github.com/TykTechnologies/tyk/user + SignatureConfig: + properties: + algorithm: + type: string + x-go-name: Algorithm + allowed_clock_skew: + format: int64 + type: integer + x-go-name: AllowedClockSkew + error_code: + format: int64 + type: integer + x-go-name: ErrorCode + error_message: + type: string + x-go-name: ErrorMessage + header: + type: string + x-go-name: Header + secret: + type: string + x-go-name: Secret + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + StorageEngineCode: + type: string + x-go-package: github.com/TykTechnologies/tyk/apidef + StringRegexMap: + properties: + match_rx: + type: string + x-go-name: MatchPattern + reverse: + type: boolean + x-go-name: Reverse + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + TemplateData: + properties: + enable_session: + type: boolean + x-go-name: EnableSession + input_type: + $ref: '#/components/schemas/RequestInputType' + template_mode: + $ref: '#/components/schemas/TemplateMode' + template_source: + type: string + x-go-name: TemplateSource + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + TemplateMeta: + properties: + method: + type: string + x-go-name: Method + path: + type: string + x-go-name: Path + template_data: + $ref: '#/components/schemas/TemplateData' + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + TemplateMode: + type: string + x-go-package: github.com/TykTechnologies/tyk/apidef + TrackEndpointMeta: + properties: + method: + type: string + x-go-name: Method + path: + type: string + x-go-name: Path + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + TransformJQMeta: + properties: + filter: + type: string + x-go-name: Filter + method: + type: string + x-go-name: Method + path: + type: string + x-go-name: Path + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + URLRewriteMeta: + properties: + MatchRegexp: + $ref: '#/components/schemas/Regexp' + match_pattern: + type: string + x-go-name: MatchPattern + method: + type: string + x-go-name: Method + path: + type: string + x-go-name: Path + rewrite_to: + type: string + x-go-name: RewriteTo + triggers: + items: + $ref: '#/components/schemas/RoutingTrigger' + type: array + x-go-name: Triggers + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + ValidatePathMeta: + properties: + error_response_code: + description: >- + Allows override of default 422 Unprocessible Entity response code + for validation errors. + format: int64 + type: integer + x-go-name: ErrorResponseCode + method: + type: string + x-go-name: Method + path: + type: string + x-go-name: Path + schema: + additionalProperties: + type: object + type: object + x-go-name: Schema + schema_b64: + type: string + x-go-name: SchemaB64 + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + VersionInfo: + properties: + paths: + properties: + black_list: + items: + type: string + type: array + x-go-name: BlackList + ignored: + items: + type: string + type: array + x-go-name: Ignored + white_list: + items: + type: string + type: array + x-go-name: WhiteList + type: object + x-go-name: Paths + expires: + type: string + x-go-name: Expires + extended_paths: + $ref: '#/components/schemas/ExtendedPathsSet' + global_headers: + additionalProperties: + type: string + type: object + x-go-name: GlobalHeaders + global_headers_remove: + items: + type: string + type: array + x-go-name: GlobalHeadersRemove + global_size_limit: + format: int64 + type: integer + x-go-name: GlobalSizeLimit + name: + type: string + x-go-name: Name + override_target: + type: string + x-go-name: OverrideTarget + use_extended_paths: + type: boolean + x-go-name: UseExtendedPaths + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + VirtualMeta: + properties: + function_source_type: + type: string + x-go-name: FunctionSourceType + function_source_uri: + type: string + x-go-name: FunctionSourceURI + method: + type: string + x-go-name: Method + path: + type: string + x-go-name: Path + proxy_on_error: + type: boolean + x-go-name: ProxyOnError + response_function_name: + type: string + x-go-name: ResponseFunctionName + use_session: + type: boolean + x-go-name: UseSession + type: object + x-go-package: github.com/TykTechnologies/tyk/apidef + apiAllKeys: + description: apiAllKeys represents a list of keys in the memory store + properties: + keys: + items: + type: string + type: array + x-go-name: APIKeys + type: object + x-go-package: github.com/TykTechnologies/tyk + apiModifyKeySuccess: + description: apiModifyKeySuccess represents when a Key modification was successful + properties: + action: + type: string + x-go-name: Action + key: + description: 'in:body' + type: string + x-go-name: Key + key_hash: + type: string + x-go-name: KeyHash + status: + type: string + x-go-name: Status + type: object + x-go-package: github.com/TykTechnologies/tyk + apiStatusMessage: + description: apiStatusMessage represents an API status message + properties: + message: + description: Response details + type: string + x-go-name: Message + status: + type: string + x-go-name: Status + type: object + x-go-package: github.com/TykTechnologies/tyk + securitySchemes: + api_key: + in: header + name: X-Tyk-Authorization + type: apiKey +security: + - api_key: [] + diff --git a/tracing.go b/tracing.go index 0fb8e9dc612..a0bddf2d2fa 100644 --- a/tracing.go +++ b/tracing.go @@ -29,25 +29,21 @@ func (tr *traceHttpRequest) toRequest() *http.Request { return r } -// Tracing HTTP request -// -// swagger:model +// TraceRequest is for tracing an HTTP request +// swagger:model TraceRequest type traceRequest struct { Request *traceHttpRequest `json:"request"` Spec *apidef.APIDefinition `json:"spec"` } -// Tracing HTTP response -// -// swagger:model +// TraceResponse is for tracing an HTTP response +// swagger:model TraceResponse type traceResponse struct { Message string `json:"message"` Response string `json:"response"` Logs string `json:"logs"` } -// swagger:operation POST /trace trace trace -// // Tracing request // Used to test API definition by sending sample request, // and analysisng output of both response and logs diff --git a/user/session.go b/user/session.go index 6ce9115f89b..b13dfe05920 100644 --- a/user/session.go +++ b/user/session.go @@ -44,6 +44,8 @@ type AccessDefinition struct { // SessionState objects represent a current API session, mainly used for rate limiting. // There's a data structure that's based on this and it's used for Protocol Buffer support, make sure to update "coprocess/proto/coprocess_session_state.proto" and generate the bindings using: cd coprocess/proto && ./update_bindings.sh +// +// swagger:model type SessionState struct { LastCheck int64 `json:"last_check" msg:"last_check"` Allowance float64 `json:"allowance" msg:"allowance"` diff --git a/utils/ci-swagger.sh b/utils/ci-swagger.sh new file mode 100755 index 00000000000..b983e6da62e --- /dev/null +++ b/utils/ci-swagger.sh @@ -0,0 +1,52 @@ +#!/bin/bash + +swagger2fileName="swagger2.yaml" +tempOpenAPIFileName="temp-swagger.yml" +tempUpdatedOpenAPIFileName="temp-swagger2.yml" +openAPIspecfileName="swagger.yml" + +fatal() { + echo "$@" >&2 + exit 1 +} + +swagger generate spec -o "$swagger2fileName" + +if [ $? -ne 0 ]; then + fatal "could not generate swagger2.0 spec to the specified path, $swagger2fileName" +fi + +swagger validate "$swagger2fileName" + +if [ $? -ne 0 ]; then + fatal "swagger spec is invalid... swagger spec is located at $swagger2fileName" +fi + +api-spec-converter --from=swagger_2 --to=openapi_3 --syntax=yaml "$swagger2fileName" > "$tempOpenAPIFileName" + +if [ $? -ne 0 ]; then + fatal "could not convert swagger2.0 spec to opeenapi 3.0" +fi + +## clean up +rm "$swagger2fileName" + +## If running this on macOS, you might need to change sed to gsed + +sed -n '1,/components:/p' $openAPIspecfileName > $tempUpdatedOpenAPIFileName + +if [ $? -ne 0 ]; then + fatal "replace operation failed step 1" +fi + +lineToStartReplaceFrom=$(grep -n "responses:" swagger.yml | tail -1 | awk '{split($0,a,":"); print a[1]}') + +sed -n "$lineToStartReplaceFrom,/components:/p" $openAPIspecfileName >> $tempUpdatedOpenAPIFileName +if [ $? -ne 0 ]; then + fatal "replace operation failed" +fi + +mv $tempUpdatedOpenAPIFileName $openAPIspecfileName + +## Ideally, CI should push $openAPIspecfileName to GitHub +## but for now, it can be committed by users and pushed alonside their changes.