Feature: OpenAPI / Swagger schema

Mailpit now has built-in OpenAPI / Swagger documentation, see #65
This commit is contained in:
Ralph Slooten
2023-03-31 17:29:04 +13:00
parent 3bb9f4162a
commit 5350e2eb08
16 changed files with 4069 additions and 84 deletions

View File

@@ -0,0 +1,28 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1.0">
<title>Mailpit API v1 documentation</title>
<meta name="referrer" content="no-referrer">
<meta name="robots" content="noindex, nofollow, noarchive">
<link rel="icon" href="../../favicon.svg">
<script src="../../dist/docs.js"></script>
</head>
<body>
<rapi-doc id="thedoc" spec-url="swagger.json" theme="light" layout="column" render-style="read" load-fonts="false"
regular-font="system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', 'Noto Sans', 'Liberation Sans', Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'"
mono-font="Courier New, Courier, System, fixed-width" font-size="large" allow-spec-url-load="false"
allow-spec-file-load="false" allow-server-selection="false" allow-search="false" allow-advanced-search="false"
bg-color="#ffffff" nav-bg-color="#e3e8ec" nav-text-color="#212529" nav-hover-bg-color="#fff"
header-color="#2c3e50" primary-color="#2c3e50" text-color="#212529">
<div slot="header">Mailpit API v1 documentation</div>
<a target='_blank' href="../../" slot="logo">
<img src="../../mailpit.svg" width="40" alt="Mailpit" />
</a>
</rapi-doc>
</body>
</html>

View File

@@ -0,0 +1,820 @@
{
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"schemes": [
"http"
],
"swagger": "2.0",
"info": {
"description": "OpenAPI 2.0 documentation for [Mailpit](https://github.com/axllent/mailpit).",
"title": "Mailpit API",
"contact": {
"name": "GitHub",
"url": "https://github.com/axllent/mailpit"
},
"license": {
"name": "MIT license",
"url": "https://github.com/axllent/mailpit/blob/develop/LICENSE"
},
"version": "v1"
},
"paths": {
"/api/v1/info": {
"get": {
"description": "Returns basic runtime information, message totals and latest release version.",
"produces": [
"application/octet-stream"
],
"schemes": [
"http",
"https"
],
"tags": [
"application"
],
"summary": "Get the application information",
"operationId": "AppInformation",
"responses": {
"200": {
"$ref": "#/responses/InfoResponse"
},
"default": {
"$ref": "#/responses/ErrorResponse"
}
}
}
},
"/api/v1/message/{ID}": {
"get": {
"description": "Returns the summary of a message, marking the message as read.",
"produces": [
"application/json"
],
"schemes": [
"http",
"https"
],
"tags": [
"message"
],
"summary": "Get message summary",
"operationId": "Message",
"parameters": [
{
"type": "string",
"description": "message id",
"name": "ID",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "Message",
"schema": {
"$ref": "#/definitions/Message"
}
},
"default": {
"$ref": "#/responses/ErrorResponse"
}
}
}
},
"/api/v1/message/{ID}/headers": {
"get": {
"description": "Returns the message headers as an array.",
"produces": [
"application/json"
],
"schemes": [
"http",
"https"
],
"tags": [
"message"
],
"summary": "Get message headers",
"operationId": "Headers",
"parameters": [
{
"type": "string",
"description": "message id",
"name": "ID",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "MessageHeaders",
"schema": {
"$ref": "#/definitions/MessageHeaders"
}
},
"default": {
"$ref": "#/responses/ErrorResponse"
}
}
}
},
"/api/v1/message/{ID}/part/{PartID}": {
"get": {
"description": "This will return the attachment part using the appropriate Content-Type.",
"produces": [
"application/*",
"image/*",
"text/*"
],
"schemes": [
"http",
"https"
],
"tags": [
"message"
],
"summary": "Get message attachment",
"operationId": "Attachment",
"parameters": [
{
"type": "string",
"description": "message id",
"name": "ID",
"in": "path",
"required": true
},
{
"type": "string",
"description": "attachment part id",
"name": "PartID",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"$ref": "#/responses/BinaryResponse"
},
"default": {
"$ref": "#/responses/ErrorResponse"
}
}
}
},
"/api/v1/message/{ID}/part/{PartID}/thumb": {
"get": {
"description": "This will return a cropped 180x120 JPEG thumbnail of an image attachment.\nIf the image is smaller than 180x120 then the image is padded. If the attachment is not an image then a blank image is returned.",
"produces": [
"image/jpeg"
],
"schemes": [
"http",
"https"
],
"tags": [
"message"
],
"summary": "Get an attachment image thumbnail",
"operationId": "Thumbnail",
"parameters": [
{
"type": "string",
"description": "message id",
"name": "ID",
"in": "path",
"required": true
},
{
"type": "string",
"description": "attachment part id",
"name": "PartID",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"$ref": "#/responses/BinaryResponse"
},
"default": {
"$ref": "#/responses/ErrorResponse"
}
}
}
},
"/api/v1/message/{ID}/raw": {
"get": {
"description": "Returns the full email source as plain text.",
"produces": [
"text/plain"
],
"schemes": [
"http",
"https"
],
"tags": [
"message"
],
"summary": "Get message source",
"operationId": "Raw",
"parameters": [
{
"type": "string",
"description": "message id",
"name": "ID",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"$ref": "#/responses/TextResponse"
},
"default": {
"$ref": "#/responses/ErrorResponse"
}
}
}
},
"/api/v1/messages": {
"get": {
"description": "Returns messages from the mailbox ordered from newest to oldest.",
"produces": [
"application/json"
],
"schemes": [
"http",
"https"
],
"tags": [
"messages"
],
"summary": "List messages",
"operationId": "GetMessages",
"parameters": [
{
"type": "integer",
"default": 0,
"description": "pagination offset",
"name": "start",
"in": "query"
},
{
"type": "integer",
"default": 50,
"description": "limit results",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"$ref": "#/responses/MessagesSummaryResponse"
},
"default": {
"$ref": "#/responses/ErrorResponse"
}
}
},
"put": {
"description": "If no IDs are provided then all messages are updated.",
"consumes": [
"application/json"
],
"produces": [
"text/plain"
],
"schemes": [
"http",
"https"
],
"tags": [
"messages"
],
"summary": "Set read status",
"operationId": "SetReadStatus",
"parameters": [
{
"description": "Message ids to update",
"name": "ids",
"in": "body",
"schema": {
"description": "Message ids to update",
"type": "object",
"$ref": "#/definitions/SetReadStatusRequest"
}
}
],
"responses": {
"200": {
"$ref": "#/responses/OKResponse"
},
"default": {
"$ref": "#/responses/ErrorResponse"
}
}
},
"delete": {
"description": "If no IDs are provided then all messages are deleted.",
"consumes": [
"application/json"
],
"produces": [
"text/plain"
],
"schemes": [
"http",
"https"
],
"tags": [
"messages"
],
"summary": "Delete messages",
"operationId": "Delete",
"parameters": [
{
"description": "Message ids to delete",
"name": "ids",
"in": "body",
"schema": {
"description": "Message ids to delete",
"type": "object",
"$ref": "#/definitions/DeleteRequest"
}
}
],
"responses": {
"200": {
"$ref": "#/responses/OKResponse"
},
"default": {
"$ref": "#/responses/ErrorResponse"
}
}
}
},
"/api/v1/search": {
"get": {
"description": "Returns the latest messages matching a search.",
"produces": [
"application/json"
],
"schemes": [
"http",
"https"
],
"tags": [
"messages"
],
"summary": "Search messages",
"operationId": "MessagesSummary",
"parameters": [
{
"type": "string",
"description": "search query",
"name": "query",
"in": "query",
"required": true
},
{
"type": "integer",
"default": 50,
"description": "limit results",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"$ref": "#/responses/MessagesSummaryResponse"
},
"default": {
"$ref": "#/responses/ErrorResponse"
}
}
}
},
"/api/v1/tags": {
"put": {
"description": "To remove all tags from a message, pass an empty tags array.",
"consumes": [
"application/json"
],
"produces": [
"text/plain"
],
"schemes": [
"http",
"https"
],
"tags": [
"tags"
],
"summary": "Set message tags",
"operationId": "SetTags",
"parameters": [
{
"description": "Message ids to update",
"name": "ids",
"in": "body",
"required": true,
"schema": {
"description": "Message ids to update",
"type": "object",
"$ref": "#/definitions/SetTagsRequest"
}
}
],
"responses": {
"200": {
"$ref": "#/responses/OKResponse"
},
"default": {
"$ref": "#/responses/ErrorResponse"
}
}
}
}
},
"definitions": {
"Address": {
"description": "An address such as \"Barry Gibbs \u003cbg@example.com\u003e\" is represented\nas Address{Name: \"Barry Gibbs\", Address: \"bg@example.com\"}.",
"type": "object",
"title": "Address represents a single mail address.",
"properties": {
"Address": {
"type": "string"
},
"Name": {
"type": "string"
}
},
"x-go-package": "net/mail"
},
"AppInformation": {
"description": "Response includes the current and latest Mailpit versions, database info, and memory usage",
"type": "object",
"properties": {
"Database": {
"description": "Database path",
"type": "string"
},
"DatabaseSize": {
"description": "Database size in bytes",
"type": "integer",
"format": "int64"
},
"LatestVersion": {
"description": "Latest Mailpit version",
"type": "string"
},
"Memory": {
"description": "Current memory usage in bytes",
"type": "integer",
"format": "uint64"
},
"Messages": {
"description": "Total number of messages in the database",
"type": "integer",
"format": "int64"
},
"Version": {
"description": "Current Mailpit version",
"type": "string"
}
},
"x-go-name": "appInformation",
"x-go-package": "github.com/axllent/mailpit/server/apiv1"
},
"Attachment": {
"description": "Attachment struct for inline and attachments",
"type": "object",
"properties": {
"ContentID": {
"description": "content id",
"type": "string"
},
"ContentType": {
"description": "content type",
"type": "string"
},
"FileName": {
"description": "file name",
"type": "string"
},
"PartID": {
"description": "attachment part id",
"type": "string"
},
"Size": {
"description": "size in bytes",
"type": "integer",
"format": "int64"
}
},
"x-go-package": "github.com/axllent/mailpit/storage"
},
"DeleteRequest": {
"description": "Delete request",
"type": "object",
"properties": {
"ids": {
"description": "ids\nin:body",
"type": "array",
"items": {
"type": "string"
},
"x-go-name": "IDs"
}
},
"x-go-name": "deleteRequest",
"x-go-package": "github.com/axllent/mailpit/server/apiv1"
},
"Message": {
"description": "Message data excluding physical attachments",
"type": "object",
"properties": {
"Attachments": {
"description": "Message attachments",
"type": "array",
"items": {
"$ref": "#/definitions/Attachment"
}
},
"Bcc": {
"description": "Bcc addresses",
"type": "array",
"items": {
"$ref": "#/definitions/Address"
}
},
"Cc": {
"description": "Cc addresses",
"type": "array",
"items": {
"$ref": "#/definitions/Address"
}
},
"Date": {
"description": "Message date if set, else date received",
"type": "string",
"format": "date-time"
},
"From": {
"$ref": "#/definitions/Address"
},
"HTML": {
"description": "Message body HTML",
"type": "string"
},
"ID": {
"description": "Unique message database id",
"type": "string"
},
"Inline": {
"description": "Inline message attachments",
"type": "array",
"items": {
"$ref": "#/definitions/Attachment"
}
},
"Read": {
"description": "Read status",
"type": "boolean"
},
"Size": {
"description": "Message size in bytes",
"type": "integer",
"format": "int64"
},
"Subject": {
"description": "Message subject",
"type": "string"
},
"Tags": {
"description": "Message tags",
"type": "array",
"items": {
"type": "string"
}
},
"Text": {
"description": "Message body text",
"type": "string"
},
"To": {
"description": "To addresses",
"type": "array",
"items": {
"$ref": "#/definitions/Address"
}
}
},
"x-go-package": "github.com/axllent/mailpit/storage"
},
"MessageHeaders": {
"description": "Message headers",
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"x-go-name": "messageHeaders",
"x-go-package": "github.com/axllent/mailpit/server/apiv1"
},
"MessageSummary": {
"description": "MessageSummary struct for frontend messages",
"type": "object",
"properties": {
"Attachments": {
"description": "Whether the message has any attachments",
"type": "integer",
"format": "int64"
},
"Bcc": {
"description": "Bcc addresses",
"type": "array",
"items": {
"$ref": "#/definitions/Address"
}
},
"Cc": {
"description": "Cc addresses",
"type": "array",
"items": {
"$ref": "#/definitions/Address"
}
},
"Created": {
"description": "Created time",
"type": "string",
"format": "date-time"
},
"From": {
"$ref": "#/definitions/Address"
},
"ID": {
"description": "Unique message database id",
"type": "string"
},
"Read": {
"description": "Read status",
"type": "boolean"
},
"Size": {
"description": "Message size in bytes (total)",
"type": "integer",
"format": "int64"
},
"Subject": {
"description": "Email subject",
"type": "string"
},
"Tags": {
"description": "Message tags",
"type": "array",
"items": {
"type": "string"
}
},
"To": {
"description": "To address",
"type": "array",
"items": {
"$ref": "#/definitions/Address"
}
}
},
"x-go-package": "github.com/axllent/mailpit/storage"
},
"MessagesSummary": {
"description": "MessagesSummary is a summary of a list of messages",
"type": "object",
"properties": {
"count": {
"description": "Number of results returned",
"type": "integer",
"format": "int64",
"x-go-name": "Count"
},
"messages": {
"description": "Messages summary\nin:body",
"type": "array",
"items": {
"$ref": "#/definitions/MessageSummary"
},
"x-go-name": "Messages"
},
"start": {
"description": "Pagination offset",
"type": "integer",
"format": "int64",
"x-go-name": "Start"
},
"tags": {
"description": "All current tags",
"type": "array",
"items": {
"type": "string"
},
"x-go-name": "Tags"
},
"total": {
"description": "Total number of messages in mailbox",
"type": "integer",
"format": "int64",
"x-go-name": "Total"
},
"unread": {
"description": "Total number of unread messages in mailbox",
"type": "integer",
"format": "int64",
"x-go-name": "Unread"
}
},
"x-go-package": "github.com/axllent/mailpit/server/apiv1"
},
"SetReadStatusRequest": {
"description": "Set read status request",
"type": "object",
"properties": {
"ids": {
"description": "ids\nin:body",
"type": "array",
"items": {
"type": "string"
},
"x-go-name": "IDs"
},
"read": {
"description": "Read status",
"type": "boolean",
"x-go-name": "Read"
}
},
"x-go-name": "setReadStatusRequest",
"x-go-package": "github.com/axllent/mailpit/server/apiv1"
},
"SetTagsRequest": {
"description": "Set tags request",
"type": "object",
"properties": {
"ids": {
"description": "ids\nin:body",
"type": "array",
"items": {
"type": "string"
},
"x-go-name": "IDs"
},
"tags": {
"description": "Tags\nin:body",
"type": "array",
"items": {
"type": "string"
},
"x-go-name": "Tags"
}
},
"x-go-name": "setTagsRequest",
"x-go-package": "github.com/axllent/mailpit/server/apiv1"
}
},
"responses": {
"BinaryResponse": {
"description": "Binary data reponse inherits the attachment's content type"
},
"ErrorResponse": {
"description": "Error reponse"
},
"InfoResponse": {
"description": "Application information",
"schema": {
"$ref": "#/definitions/AppInformation"
},
"headers": {
"Body": {
"description": "Application information"
}
}
},
"MessagesSummaryResponse": {
"description": "Message summary",
"schema": {
"$ref": "#/definitions/MessagesSummary"
}
},
"OKResponse": {
"description": "Plain text \"ok\" reponse"
},
"TextResponse": {
"description": "Plain text response"
}
}
}