From da1b7ec64a8c56e08d72dad5716a45c4ee415bdc Mon Sep 17 00:00:00 2001 From: Ian Kent Date: Tue, 24 Feb 2015 22:44:34 +0000 Subject: [PATCH] API v2 search and message list documentation for #36 --- docs/APIv2.md | 8 ++ docs/APIv2/swagger-2.0.json | 259 ++++++++++++++++++++++++++++++++++++ docs/APIv2/swagger-2.0.yaml | 186 ++++++++++++++++++++++++++ 3 files changed, 453 insertions(+) create mode 100644 docs/APIv2.md create mode 100644 docs/APIv2/swagger-2.0.json create mode 100644 docs/APIv2/swagger-2.0.yaml diff --git a/docs/APIv2.md b/docs/APIv2.md new file mode 100644 index 0000000..36537b0 --- /dev/null +++ b/docs/APIv2.md @@ -0,0 +1,8 @@ +MailHog API v2 +============== + +The v2 API is hopefully less of a mess than v1. + +The specification is written in [Swagger 2.0](http://swagger.io/). + +See the YAML and JSON specifications in the [APIv2](./APIv2) directory. diff --git a/docs/APIv2/swagger-2.0.json b/docs/APIv2/swagger-2.0.json new file mode 100644 index 0000000..a582fca --- /dev/null +++ b/docs/APIv2/swagger-2.0.json @@ -0,0 +1,259 @@ +{ + "swagger": "2.0", + "info": { + "version": "2.0.0", + "title": "MailHog API" + }, + "paths": { + "/api/v2/messages": { + "get": { + "description": "Retrieve a list of messages\n", + "parameters": [ + { + "name": "start", + "in": "query", + "description": "Start index", + "required": false, + "type": "number", + "format": "int64", + "default": 0 + }, + { + "name": "limit", + "in": "query", + "description": "Number of messages", + "required": false, + "type": "number", + "format": "int64", + "default": 50 + } + ], + "responses": { + "200": { + "description": "Successful response", + "schema": { + "title": "Messages", + "type": "object", + "properties": { + "total": { + "type": "number", + "format": "int64", + "description": "Total number of stored messages" + }, + "start": { + "type": "number", + "format": "int64", + "description": "Start index of first returned message" + }, + "count": { + "type": "number", + "format": "int64", + "description": "Number of returned messages" + }, + "messages": { + "type": "array", + "items": { + "title": "Message", + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "from": { + "title": "Path", + "type": "object", + "properties": { + "relays": { + "type": "array", + "items": { + "type": "string" + } + }, + "mailbox": { + "type": "string" + }, + "domain": { + "type": "string" + }, + "params": { + "type": "string" + } + } + }, + "to": { + "type": "array", + "items": { + "title": "Path", + "type": "object", + "properties": { + "relays": { + "type": "array", + "items": { + "type": "string" + } + }, + "mailbox": { + "type": "string" + }, + "domain": { + "type": "string" + }, + "params": { + "type": "string" + } + } + } + }, + "headers": { + "type": "object" + }, + "size": { + "type": "number", + "format": "int64" + }, + "created": { + "type": "string", + "format": "date-time" + } + } + } + } + } + } + } + } + } + }, + "/api/v2/search": { + "get": { + "description": "Search messages\n", + "parameters": [ + { + "name": "kind", + "in": "query", + "description": "Kind of search", + "required": true, + "type": "string", + "enum": [ + "from", + "to", + "containing" + ] + }, + { + "name": "start", + "in": "query", + "description": "Start index", + "required": false, + "type": "number", + "format": "int64", + "default": 0 + }, + { + "name": "limit", + "in": "query", + "description": "Number of messages", + "required": false, + "type": "number", + "format": "int64", + "default": 50 + } + ], + "responses": { + "200": { + "description": "Successful response", + "schema": { + "title": "Messages", + "type": "object", + "properties": { + "total": { + "type": "number", + "format": "int64", + "description": "Total number of stored messages" + }, + "start": { + "type": "number", + "format": "int64", + "description": "Start index of first returned message" + }, + "count": { + "type": "number", + "format": "int64", + "description": "Number of returned messages" + }, + "messages": { + "type": "array", + "items": { + "title": "Message", + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "from": { + "title": "Path", + "type": "object", + "properties": { + "relays": { + "type": "array", + "items": { + "type": "string" + } + }, + "mailbox": { + "type": "string" + }, + "domain": { + "type": "string" + }, + "params": { + "type": "string" + } + } + }, + "to": { + "type": "array", + "items": { + "title": "Path", + "type": "object", + "properties": { + "relays": { + "type": "array", + "items": { + "type": "string" + } + }, + "mailbox": { + "type": "string" + }, + "domain": { + "type": "string" + }, + "params": { + "type": "string" + } + } + } + }, + "headers": { + "type": "object" + }, + "size": { + "type": "number", + "format": "int64" + }, + "created": { + "type": "string", + "format": "date-time" + } + } + } + } + } + } + } + } + } + } + } +} \ No newline at end of file diff --git a/docs/APIv2/swagger-2.0.yaml b/docs/APIv2/swagger-2.0.yaml new file mode 100644 index 0000000..b4c84cf --- /dev/null +++ b/docs/APIv2/swagger-2.0.yaml @@ -0,0 +1,186 @@ +swagger: '2.0' + +info: + version: "2.0.0" + title: MailHog API + +paths: + /api/v2/messages: + get: + description: | + Retrieve a list of messages + parameters: + - + name: start + in: query + description: Start index + required: false + type: number + format: int64 + default: 0 + - + name: limit + in: query + description: Number of messages + required: false + type: number + format: int64 + default: 50 + responses: + 200: + description: Successful response + schema: + title: Messages + type: object + properties: + total: + type: number + format: int64 + description: Total number of stored messages + start: + type: number + format: int64 + description: Start index of first returned message + count: + type: number + format: int64 + description: Number of returned messages + messages: + type: array + items: + title: Message + type: object + properties: + id: + type: string + from: + title: Path + type: object + properties: + relays: + type: array + items: + type: string + mailbox: + type: string + domain: + type: string + params: + type: string + to: + type: array + items: + title: Path + type: object + properties: + relays: + type: array + items: + type: string + mailbox: + type: string + domain: + type: string + params: + type: string + headers: + type: object + size: + type: number + format: int64 + created: + type: string + format: date-time + /api/v2/search: + get: + description: | + Search messages + parameters: + - + name: kind + in: query + description: Kind of search + required: true + type: string + enum: [ from, to, containing ] + - + name: start + in: query + description: Start index + required: false + type: number + format: int64 + default: 0 + - + name: limit + in: query + description: Number of messages + required: false + type: number + format: int64 + default: 50 + responses: + 200: + description: Successful response + schema: + title: Messages + type: object + properties: + total: + type: number + format: int64 + description: Total number of stored messages + start: + type: number + format: int64 + description: Start index of first returned message + count: + type: number + format: int64 + description: Number of returned messages + messages: + type: array + items: + title: Message + type: object + properties: + id: + type: string + from: + title: Path + type: object + properties: + relays: + type: array + items: + type: string + mailbox: + type: string + domain: + type: string + params: + type: string + to: + type: array + items: + title: Path + type: object + properties: + relays: + type: array + items: + type: string + mailbox: + type: string + domain: + type: string + params: + type: string + headers: + type: object + size: + type: number + format: int64 + created: + type: string + format: date-time \ No newline at end of file