Created
October 19, 2017 03:25
-
-
Save rgstephens/ff49f0e16ce6737d2fc6b149e2809929 to your computer and use it in GitHub Desktop.
Client API Swagger JSON Definition
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| { | |
| "swagger": "2.0", | |
| "info": { | |
| "description": "This is a sample client management API. The YAML definition for this API can be found at [https://gist.github.com/358ef6d256a69084357e139f8c7db19b.git](https://gist.github.com/358ef6d256a69084357e139f8c7db19b.git)", | |
| "version": "0.1.0", | |
| "title": "Client API", | |
| "contact": { | |
| "email": "[email protected]" | |
| }, | |
| "license": { | |
| "name": "Apache 2.0", | |
| "url": "http://www.apache.org/licenses/LICENSE-2.0.html" | |
| } | |
| }, | |
| "host": "10.1.1.3:8081", | |
| "basePath": "/", | |
| "tags": [ | |
| { | |
| "name": "user", | |
| "description": "User Operations", | |
| "externalDocs": { | |
| "description": "Find out more", | |
| "url": "http://google.com" | |
| } | |
| }, | |
| { | |
| "name": "client", | |
| "description": "Client Operations", | |
| "externalDocs": { | |
| "description": "Find out more", | |
| "url": "http://google.com" | |
| } | |
| } | |
| ], | |
| "schemes": [ | |
| "http" | |
| ], | |
| "paths": { | |
| "/client": { | |
| "post": { | |
| "tags": [ | |
| "client" | |
| ], | |
| "summary": "Add a new client", | |
| "description": "", | |
| "operationId": "addClient", | |
| "consumes": [ | |
| "application/json", | |
| "application/xml" | |
| ], | |
| "produces": [ | |
| "application/xml", | |
| "application/json" | |
| ], | |
| "parameters": [ | |
| { | |
| "in": "body", | |
| "name": "body", | |
| "description": "Client object that needs to be added", | |
| "required": true, | |
| "schema": { | |
| "$ref": "#/definitions/Client" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "405": { | |
| "description": "Invalid input" | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "client_auth": [ | |
| "write:clients", | |
| "read:clients" | |
| ] | |
| } | |
| ] | |
| }, | |
| "put": { | |
| "tags": [ | |
| "client" | |
| ], | |
| "summary": "Update an existing client", | |
| "description": "", | |
| "operationId": "updateClient", | |
| "consumes": [ | |
| "application/json", | |
| "application/xml" | |
| ], | |
| "produces": [ | |
| "application/xml", | |
| "application/json" | |
| ], | |
| "parameters": [ | |
| { | |
| "in": "body", | |
| "name": "body", | |
| "description": "Client object that needs to be added", | |
| "required": true, | |
| "schema": { | |
| "$ref": "#/definitions/Client" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "400": { | |
| "description": "Invalid ID supplied" | |
| }, | |
| "404": { | |
| "description": "Client not found" | |
| }, | |
| "405": { | |
| "description": "Validation exception" | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "client_auth": [ | |
| "write:clients", | |
| "read:clients" | |
| ] | |
| } | |
| ] | |
| } | |
| }, | |
| "/client/findByStatus": { | |
| "get": { | |
| "tags": [ | |
| "client" | |
| ], | |
| "summary": "Finds Clients by status", | |
| "description": "Multiple status values can be provided with comma separated strings", | |
| "operationId": "findClientsByStatus", | |
| "produces": [ | |
| "application/xml", | |
| "application/json" | |
| ], | |
| "parameters": [ | |
| { | |
| "name": "status", | |
| "in": "query", | |
| "description": "Status values that need to be considered for filter", | |
| "required": true, | |
| "type": "array", | |
| "items": { | |
| "type": "string", | |
| "enum": [ | |
| "available", | |
| "pending", | |
| "sold" | |
| ], | |
| "default": "available" | |
| }, | |
| "collectionFormat": "multi" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "successful operation", | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/Client" | |
| } | |
| } | |
| }, | |
| "400": { | |
| "description": "Invalid status value" | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "client_auth": [ | |
| "write:clients", | |
| "read:clients" | |
| ] | |
| } | |
| ] | |
| } | |
| }, | |
| "/client/findByTags": { | |
| "get": { | |
| "tags": [ | |
| "client" | |
| ], | |
| "summary": "Finds Clients by tags", | |
| "description": "Muliple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.", | |
| "operationId": "findClientsByTags", | |
| "produces": [ | |
| "application/xml", | |
| "application/json" | |
| ], | |
| "parameters": [ | |
| { | |
| "name": "tags", | |
| "in": "query", | |
| "description": "Tags to filter by", | |
| "required": true, | |
| "type": "array", | |
| "items": { | |
| "type": "string" | |
| }, | |
| "collectionFormat": "multi" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "successful operation", | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/Client" | |
| } | |
| } | |
| }, | |
| "400": { | |
| "description": "Invalid tag value" | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "client_auth": [ | |
| "write:clients", | |
| "read:clients" | |
| ] | |
| } | |
| ], | |
| "deprecated": true | |
| } | |
| }, | |
| "/client/{clientId}": { | |
| "get": { | |
| "tags": [ | |
| "client" | |
| ], | |
| "summary": "Find client by ID", | |
| "description": "Returns a single client", | |
| "operationId": "getClientById", | |
| "produces": [ | |
| "application/xml", | |
| "application/json" | |
| ], | |
| "parameters": [ | |
| { | |
| "name": "clientId", | |
| "in": "path", | |
| "description": "ID of client to return", | |
| "required": true, | |
| "type": "integer", | |
| "format": "int64" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "successful operation", | |
| "schema": { | |
| "$ref": "#/definitions/Client" | |
| } | |
| }, | |
| "400": { | |
| "description": "Invalid ID supplied" | |
| }, | |
| "404": { | |
| "description": "Client not found" | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "api_key": [] | |
| } | |
| ] | |
| }, | |
| "post": { | |
| "tags": [ | |
| "client" | |
| ], | |
| "summary": "Updates a client with form data", | |
| "description": "", | |
| "operationId": "updateClientWithForm", | |
| "consumes": [ | |
| "application/x-www-form-urlencoded" | |
| ], | |
| "produces": [ | |
| "application/xml", | |
| "application/json" | |
| ], | |
| "parameters": [ | |
| { | |
| "name": "clientId", | |
| "in": "path", | |
| "description": "ID of client that needs to be updated", | |
| "required": true, | |
| "type": "integer", | |
| "format": "int64" | |
| }, | |
| { | |
| "name": "name", | |
| "in": "formData", | |
| "description": "Updated name of the client", | |
| "required": false, | |
| "type": "string" | |
| }, | |
| { | |
| "name": "status", | |
| "in": "formData", | |
| "description": "Updated status of the client", | |
| "required": false, | |
| "type": "string" | |
| } | |
| ], | |
| "responses": { | |
| "405": { | |
| "description": "Invalid input" | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "client_auth": [ | |
| "write:clients", | |
| "read:clients" | |
| ] | |
| } | |
| ] | |
| }, | |
| "delete": { | |
| "tags": [ | |
| "client" | |
| ], | |
| "summary": "Deletes a client", | |
| "description": "", | |
| "operationId": "deleteClient", | |
| "produces": [ | |
| "application/xml", | |
| "application/json" | |
| ], | |
| "parameters": [ | |
| { | |
| "name": "api_key", | |
| "in": "header", | |
| "required": false, | |
| "type": "string" | |
| }, | |
| { | |
| "name": "clientId", | |
| "in": "path", | |
| "description": "Client id to delete", | |
| "required": true, | |
| "type": "integer", | |
| "format": "int64" | |
| } | |
| ], | |
| "responses": { | |
| "400": { | |
| "description": "Invalid ID supplied" | |
| }, | |
| "404": { | |
| "description": "Client not found" | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "client_auth": [ | |
| "write:clients", | |
| "read:clients" | |
| ] | |
| } | |
| ] | |
| } | |
| }, | |
| "/user": { | |
| "post": { | |
| "tags": [ | |
| "user" | |
| ], | |
| "summary": "Create user", | |
| "description": "This can only be done by the logged in user.", | |
| "operationId": "createUser", | |
| "produces": [ | |
| "application/xml", | |
| "application/json" | |
| ], | |
| "parameters": [ | |
| { | |
| "in": "body", | |
| "name": "body", | |
| "description": "Created user object", | |
| "required": true, | |
| "schema": { | |
| "$ref": "#/definitions/User" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "default": { | |
| "description": "successful operation" | |
| } | |
| } | |
| } | |
| }, | |
| "/user/createWithArray": { | |
| "post": { | |
| "tags": [ | |
| "user" | |
| ], | |
| "summary": "Creates list of users with given input array", | |
| "description": "", | |
| "operationId": "createUsersWithArrayInput", | |
| "produces": [ | |
| "application/xml", | |
| "application/json" | |
| ], | |
| "parameters": [ | |
| { | |
| "in": "body", | |
| "name": "body", | |
| "description": "List of user object", | |
| "required": true, | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/User" | |
| } | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "default": { | |
| "description": "successful operation" | |
| } | |
| } | |
| } | |
| }, | |
| "/user/createWithList": { | |
| "post": { | |
| "tags": [ | |
| "user" | |
| ], | |
| "summary": "Creates list of users with given input array", | |
| "description": "", | |
| "operationId": "createUsersWithListInput", | |
| "produces": [ | |
| "application/xml", | |
| "application/json" | |
| ], | |
| "parameters": [ | |
| { | |
| "in": "body", | |
| "name": "body", | |
| "description": "List of user object", | |
| "required": true, | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/User" | |
| } | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "default": { | |
| "description": "successful operation" | |
| } | |
| } | |
| } | |
| }, | |
| "/user/login": { | |
| "get": { | |
| "tags": [ | |
| "user" | |
| ], | |
| "summary": "Logs user into the system", | |
| "description": "", | |
| "operationId": "loginUser", | |
| "produces": [ | |
| "application/xml", | |
| "application/json" | |
| ], | |
| "parameters": [ | |
| { | |
| "name": "username", | |
| "in": "query", | |
| "description": "The user name for login", | |
| "required": true, | |
| "type": "string" | |
| }, | |
| { | |
| "name": "password", | |
| "in": "query", | |
| "description": "The password for login in clear text", | |
| "required": true, | |
| "type": "string" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "successful operation", | |
| "schema": { | |
| "type": "string" | |
| }, | |
| "headers": { | |
| "X-Rate-Limit": { | |
| "type": "integer", | |
| "format": "int32", | |
| "description": "calls per hour allowed by the user" | |
| }, | |
| "X-Expires-After": { | |
| "type": "string", | |
| "format": "date-time", | |
| "description": "date in UTC when token expires" | |
| } | |
| } | |
| }, | |
| "400": { | |
| "description": "Invalid username/password supplied" | |
| } | |
| } | |
| } | |
| }, | |
| "/user/logout": { | |
| "get": { | |
| "tags": [ | |
| "user" | |
| ], | |
| "summary": "Logs out current logged in user session", | |
| "description": "", | |
| "operationId": "logoutUser", | |
| "produces": [ | |
| "application/xml", | |
| "application/json" | |
| ], | |
| "parameters": [], | |
| "responses": { | |
| "default": { | |
| "description": "successful operation" | |
| } | |
| } | |
| } | |
| }, | |
| "/user/{username}": { | |
| "get": { | |
| "tags": [ | |
| "user" | |
| ], | |
| "summary": "Get user by user name", | |
| "description": "", | |
| "operationId": "getUserByName", | |
| "produces": [ | |
| "application/xml", | |
| "application/json" | |
| ], | |
| "parameters": [ | |
| { | |
| "name": "username", | |
| "in": "path", | |
| "description": "The name that needs to be fetched. Use user1 for testing. ", | |
| "required": true, | |
| "type": "string" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "successful operation", | |
| "schema": { | |
| "$ref": "#/definitions/User" | |
| } | |
| }, | |
| "400": { | |
| "description": "Invalid username supplied" | |
| }, | |
| "404": { | |
| "description": "User not found" | |
| } | |
| } | |
| }, | |
| "put": { | |
| "tags": [ | |
| "user" | |
| ], | |
| "summary": "Updated user", | |
| "description": "This can only be done by the logged in user.", | |
| "operationId": "updateUser", | |
| "produces": [ | |
| "application/xml", | |
| "application/json" | |
| ], | |
| "parameters": [ | |
| { | |
| "name": "username", | |
| "in": "path", | |
| "description": "name that need to be updated", | |
| "required": true, | |
| "type": "string" | |
| }, | |
| { | |
| "in": "body", | |
| "name": "body", | |
| "description": "Updated user object", | |
| "required": true, | |
| "schema": { | |
| "$ref": "#/definitions/User" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "400": { | |
| "description": "Invalid user supplied" | |
| }, | |
| "404": { | |
| "description": "User not found" | |
| } | |
| } | |
| }, | |
| "delete": { | |
| "tags": [ | |
| "user" | |
| ], | |
| "summary": "Delete user", | |
| "description": "This can only be done by the logged in user.", | |
| "operationId": "deleteUser", | |
| "produces": [ | |
| "application/xml", | |
| "application/json" | |
| ], | |
| "parameters": [ | |
| { | |
| "name": "username", | |
| "in": "path", | |
| "description": "The name that needs to be deleted", | |
| "required": true, | |
| "type": "string" | |
| } | |
| ], | |
| "responses": { | |
| "400": { | |
| "description": "Invalid username supplied" | |
| }, | |
| "404": { | |
| "description": "User not found" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "securityDefinitions": { | |
| "client_auth": { | |
| "type": "oauth2", | |
| "authorizationUrl": "http://clientstore.swagger.io/oauth/dialog", | |
| "flow": "implicit", | |
| "scopes": { | |
| "write:clients": "modify clients in your account", | |
| "read:clients": "read your clients" | |
| } | |
| }, | |
| "api_key": { | |
| "type": "apiKey", | |
| "name": "api_key", | |
| "in": "header" | |
| } | |
| }, | |
| "definitions": { | |
| "Order": { | |
| "type": "object", | |
| "properties": { | |
| "id": { | |
| "type": "integer", | |
| "format": "int64" | |
| }, | |
| "clientId": { | |
| "type": "integer", | |
| "format": "int64" | |
| }, | |
| "quantity": { | |
| "type": "integer", | |
| "format": "int32" | |
| }, | |
| "shipDate": { | |
| "type": "string", | |
| "format": "date-time" | |
| }, | |
| "status": { | |
| "type": "string", | |
| "description": "Order Status", | |
| "enum": [ | |
| "placed", | |
| "approved", | |
| "delivered" | |
| ] | |
| }, | |
| "complete": { | |
| "type": "boolean", | |
| "default": false | |
| } | |
| }, | |
| "xml": { | |
| "name": "Order" | |
| } | |
| }, | |
| "Category": { | |
| "type": "object", | |
| "properties": { | |
| "id": { | |
| "type": "integer", | |
| "format": "int64" | |
| }, | |
| "name": { | |
| "type": "string" | |
| } | |
| }, | |
| "xml": { | |
| "name": "Category" | |
| } | |
| }, | |
| "User": { | |
| "type": "object", | |
| "properties": { | |
| "id": { | |
| "type": "integer", | |
| "format": "int64" | |
| }, | |
| "username": { | |
| "type": "string" | |
| }, | |
| "firstName": { | |
| "type": "string" | |
| }, | |
| "lastName": { | |
| "type": "string" | |
| }, | |
| "email": { | |
| "type": "string" | |
| }, | |
| "password": { | |
| "type": "string" | |
| }, | |
| "phone": { | |
| "type": "string" | |
| }, | |
| "userStatus": { | |
| "type": "integer", | |
| "format": "int32", | |
| "description": "User Status" | |
| } | |
| }, | |
| "xml": { | |
| "name": "User" | |
| } | |
| }, | |
| "Tag": { | |
| "type": "object", | |
| "properties": { | |
| "id": { | |
| "type": "integer", | |
| "format": "int64" | |
| }, | |
| "name": { | |
| "type": "string" | |
| } | |
| }, | |
| "xml": { | |
| "name": "Tag" | |
| } | |
| }, | |
| "Client": { | |
| "type": "object", | |
| "required": [ | |
| "name", | |
| "photoUrls" | |
| ], | |
| "properties": { | |
| "id": { | |
| "type": "integer", | |
| "format": "int64" | |
| }, | |
| "category": { | |
| "$ref": "#/definitions/Category" | |
| }, | |
| "name": { | |
| "type": "string", | |
| "example": "doggie" | |
| }, | |
| "photoUrls": { | |
| "type": "array", | |
| "xml": { | |
| "name": "photoUrl", | |
| "wrapped": true | |
| }, | |
| "items": { | |
| "type": "string" | |
| } | |
| }, | |
| "tags": { | |
| "type": "array", | |
| "xml": { | |
| "name": "tag", | |
| "wrapped": true | |
| }, | |
| "items": { | |
| "$ref": "#/definitions/Tag" | |
| } | |
| }, | |
| "status": { | |
| "type": "string", | |
| "description": "client status in the store", | |
| "enum": [ | |
| "available", | |
| "pending", | |
| "sold" | |
| ] | |
| } | |
| }, | |
| "xml": { | |
| "name": "Client" | |
| } | |
| }, | |
| "ApiResponse": { | |
| "type": "object", | |
| "properties": { | |
| "code": { | |
| "type": "integer", | |
| "format": "int32" | |
| }, | |
| "type": { | |
| "type": "string" | |
| }, | |
| "message": { | |
| "type": "string" | |
| } | |
| } | |
| } | |
| }, | |
| "externalDocs": { | |
| "description": "Find out more about Swagger", | |
| "url": "http://swagger.io" | |
| } | |
| } |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment