1
0
mirror of https://github.com/axllent/mailpit.git synced 2025-03-17 21:18:19 +02:00

Swagger: Update swagger documentation

See #188
This commit is contained in:
Ralph Slooten 2023-10-15 19:24:06 +13:00
parent eeac32d09b
commit cded4d25fc
4 changed files with 254 additions and 228 deletions

View File

@ -144,11 +144,11 @@ func Search(w http.ResponseWriter, r *http.Request) {
// DeleteSearch will delete all messages matching a search
func DeleteSearch(w http.ResponseWriter, r *http.Request) {
// swagger:route DELETE /api/v1/search messages MessagesSummary
// swagger:route DELETE /api/v1/search messages DeleteSearch
//
// # Delete messages by search
//
// Deletes messages matching a search.
// Delete all messages matching a search.
//
// Produces:
// - application/json
@ -196,7 +196,7 @@ func GetMessage(w http.ResponseWriter, r *http.Request) {
// Parameters:
// + name: ID
// in: path
// description: Database ID
// description: Message database ID
// required: true
// type: string
//
@ -237,7 +237,7 @@ func DownloadAttachment(w http.ResponseWriter, r *http.Request) {
// Parameters:
// + name: ID
// in: path
// description: Database ID
// description: Message database ID
// required: true
// type: string
// + name: PartID
@ -362,11 +362,11 @@ func DownloadRaw(w http.ResponseWriter, r *http.Request) {
// DeleteMessages (method: DELETE) deletes all messages matching IDS.
func DeleteMessages(w http.ResponseWriter, r *http.Request) {
// swagger:route DELETE /api/v1/messages messages Delete
// swagger:route DELETE /api/v1/messages messages DeleteMessages
//
// # Delete messages
//
// If no IDs are provided then all messages are deleted.
// Delete individual or all messages. If no IDs are provided then all messages are deleted.
//
// Consumes:
// - application/json
@ -376,13 +376,6 @@ func DeleteMessages(w http.ResponseWriter, r *http.Request) {
//
// Schemes: http, https
//
// Parameters:
// + name: ids
// in: body
// description: Database IDs to delete
// required: false
// type: DeleteRequest
//
// Responses:
// 200: OKResponse
// default: ErrorResponse
@ -406,7 +399,7 @@ func DeleteMessages(w http.ResponseWriter, r *http.Request) {
}
}
w.Header().Add("Content-Type", "application/json")
w.Header().Add("Content-Type", "application/plain")
_, _ = w.Write([]byte("ok"))
}
@ -427,13 +420,6 @@ func SetReadStatus(w http.ResponseWriter, r *http.Request) {
//
// Schemes: http, https
//
// Parameters:
// + name: ids
// in: body
// description: Database IDs to update
// required: false
// type: SetReadStatusRequest
//
// Responses:
// 200: OKResponse
// default: ErrorResponse
@ -491,7 +477,7 @@ func SetReadStatus(w http.ResponseWriter, r *http.Request) {
// GetTags (method: GET) will get all tags currently in use
func GetTags(w http.ResponseWriter, _ *http.Request) {
// swagger:route GET /api/v1/tags tags SetTags
// swagger:route GET /api/v1/tags tags GetTags
//
// # Get all current tags
//
@ -524,7 +510,7 @@ func SetTags(w http.ResponseWriter, r *http.Request) {
//
// # Set message tags
//
// To remove all tags from a message, pass an empty tags array.
// This will overwrite any existing tags for selected message database IDs. To remove all tags from a message, pass an empty tags array.
//
// Consumes:
// - application/json
@ -534,13 +520,6 @@ func SetTags(w http.ResponseWriter, r *http.Request) {
//
// Schemes: http, https
//
// Parameters:
// + name: ids
// in: body
// description: Database IDs to update
// required: true
// type: SetTagsRequest
//
// Responses:
// 200: OKResponse
// default: ErrorResponse
@ -576,11 +555,11 @@ func SetTags(w http.ResponseWriter, r *http.Request) {
// ReleaseMessage (method: POST) will release a message via a pre-configured external SMTP server.
// If no IDs are provided then all messages are updated.
func ReleaseMessage(w http.ResponseWriter, r *http.Request) {
// swagger:route POST /api/v1/message/{ID}/release message Release
// swagger:route POST /api/v1/message/{ID}/release message ReleaseMessage
//
// # Release message
//
// Release a message via a pre-configured external SMTP server..
// Release a message via a pre-configured external SMTP server. This is only enabled if message relaying has been configured.
//
// Consumes:
// - application/json
@ -590,18 +569,6 @@ func ReleaseMessage(w http.ResponseWriter, r *http.Request) {
//
// Schemes: http, https
//
// Parameters:
// + name: ID
// in: path
// description: Database ID
// required: true
// type: string
// + name: to
// in: body
// description: Array of email addresses to release message to
// required: true
// type: ReleaseMessageRequest
//
// Responses:
// 200: OKResponse
// default: ErrorResponse
@ -618,7 +585,7 @@ func ReleaseMessage(w http.ResponseWriter, r *http.Request) {
decoder := json.NewDecoder(r.Body)
data := releaseMessageRequest{}
data := releaseMessageRequestBody{}
if err := decoder.Decode(&data); err != nil {
httpError(w, err.Error())
@ -702,7 +669,7 @@ func ReleaseMessage(w http.ResponseWriter, r *http.Request) {
// HTMLCheck returns a summary of the HTML client support
func HTMLCheck(w http.ResponseWriter, r *http.Request) {
// swagger:route GET /api/v1/message/{ID}/html-check Other HTMLCheckResponse
// swagger:route GET /api/v1/message/{ID}/html-check Other HTMLCheck
//
// # HTML check (beta)
//
@ -716,13 +683,6 @@ func HTMLCheck(w http.ResponseWriter, r *http.Request) {
//
// Schemes: http, https
//
// Parameters:
// + name: ID
// in: path
// description: Database ID
// required: true
// type: string
//
// Responses:
// 200: HTMLCheckResponse
// default: ErrorResponse
@ -754,7 +714,7 @@ func HTMLCheck(w http.ResponseWriter, r *http.Request) {
// LinkCheck returns a summary of links in the email
func LinkCheck(w http.ResponseWriter, r *http.Request) {
// swagger:route GET /api/v1/message/{ID}/link-check Other LinkCheckResponse
// swagger:route GET /api/v1/message/{ID}/link-check Other LinkCheck
//
// # Link check (beta)
//
@ -768,19 +728,6 @@ func LinkCheck(w http.ResponseWriter, r *http.Request) {
//
// Schemes: http, https
//
// Parameters:
// + name: ID
// in: path
// description: Database ID
// required: true
// type: string
// + name: follow
// in: query
// description: Follow redirects
// required: false
// type: boolean
// default: false
//
// Responses:
// 200: LinkCheckResponse
// default: ErrorResponse

View File

@ -22,9 +22,6 @@ type MessagesSummary struct {
// Total number of messages matching current query
MessagesCount int `json:"messages_count"`
// // Number of results returned on current page
// Count int `json:"count"`
// Pagination offset
Start int `json:"start"`
@ -32,7 +29,7 @@ type MessagesSummary struct {
Tags []string `json:"tags"`
// Messages summary
// in:body
// in: body
Messages []storage.MessageSummary `json:"messages"`
}

View File

@ -6,6 +6,8 @@ package apiv1
// swagger:response InfoResponse
type infoResponse struct {
// Application information
//
// in: body
Body appInformation
}
@ -13,6 +15,8 @@ type infoResponse struct {
// swagger:response WebUIConfigurationResponse
type webUIConfigurationResponse struct {
// Web UI configuration settings
//
// in: body
Body webUIConfiguration
}
@ -28,81 +32,137 @@ type messagesSummaryResponse struct {
// swagger:model MessageHeaders
type messageHeaders map[string][]string
// swagger:parameters DeleteMessages
type deleteMessagesParams struct {
// in: body
Body *deleteMessagesRequestBody
}
// Delete request
// swagger:model DeleteRequest
type deleteRequest struct {
// ids
// in:body
type deleteMessagesRequestBody struct {
// Array of message database IDs
//
// required: false
// example: ["5dec4247-812e-4b77-9101-e25ad406e9ea", "8ac66bbc-2d9a-4c41-ad99-00aa75fa674e"]
IDs []string `json:"ids"`
}
// swagger:parameters SetReadStatus
type setReadStatusParams struct {
// in: body
Body *setReadStatusRequestBody
}
// Set read status request
// swagger:model SetReadStatusRequest
type setReadStatusRequest struct {
// swagger:model setReadStatusRequestBody
type setReadStatusRequestBody struct {
// Read status
//
// required: false
// default: false
// example: true
Read bool `json:"read"`
// ids
// in:body
// Array of message database IDs
//
// required: false
// example: ["5dec4247-812e-4b77-9101-e25ad406e9ea", "8ac66bbc-2d9a-4c41-ad99-00aa75fa674e"]
IDs []string `json:"ids"`
}
// swagger:parameters SetTags
type setTagsParams struct {
// in: body
Body *setTagsRequestBody
}
// Set tags request
// swagger:model SetTagsRequest
type setTagsRequest struct {
// Tags
// in:body
// swagger:model setTagsRequestBody
type setTagsRequestBody struct {
// Array of tag names to set
//
// required: true
// example: ["Tag 1", "Tag 2"]
Tags []string `json:"tags"`
// IDs
// in:body
// Array of message database IDs
//
// required: true
// example: ["5dec4247-812e-4b77-9101-e25ad406e9ea", "8ac66bbc-2d9a-4c41-ad99-00aa75fa674e"]
IDs []string `json:"ids"`
}
// swagger:parameters ReleaseMessage
type releaseMessageParams struct {
// Message database ID
//
// in: path
// description: Message database ID
// required: true
ID string
// in: body
Body *releaseMessageRequestBody
}
// Release request
// swagger:model ReleaseMessageRequest
type releaseMessageRequest struct {
// To
// in:body
// swagger:model releaseMessageRequestBody
type releaseMessageRequestBody struct {
// Array of email addresses to relay the message to
//
// required: true
// example: ["user1@example.com", "user2@example.com"]
To []string `json:"to"`
}
// swagger:parameters HTMLCheck
type htmlCheckParams struct {
// Message database ID
//
// in: path
// description: Message database ID
// required: true
ID string
}
// swagger:parameters LinkCheck
type linkCheckParams struct {
// Message database ID
//
// in: path
// description: Message database ID
// required: true
ID string
// Follow redirects
//
// in: query
// description: Follow redirects
// required: false
// default: false
Follow string `json:"follow"`
}
// Binary data response inherits the attachment's content type
// swagger:response BinaryResponse
type binaryResponse struct {
// in: body
Body string
}
type binaryResponse string
// Plain text response
// swagger:response TextResponse
type textResponse struct {
// in: body
Body string
}
type textResponse string
// HTML response
// swagger:response HTMLResponse
type htmlResponse struct {
// in: body
Body string
}
type htmlResponse string
// Error response
// swagger:response ErrorResponse
type errorResponse struct {
// The error message
// in: body
Body string
}
type errorResponse string
// Plain text "ok" response
// swagger:response OKResponse
type okResponse struct {
// Default response
// in: body
Body string
}
type okResponse string
// Plain JSON array response
// swagger:response ArrayResponse

View File

@ -66,7 +66,7 @@
"parameters": [
{
"type": "string",
"description": "Database ID",
"description": "Message database ID",
"name": "ID",
"in": "path",
"required": true
@ -136,11 +136,11 @@
"Other"
],
"summary": "HTML check (beta)",
"operationId": "HTMLCheckResponse",
"operationId": "HTMLCheck",
"parameters": [
{
"type": "string",
"description": "Database ID",
"description": "Message database ID",
"name": "ID",
"in": "path",
"required": true
@ -173,18 +173,19 @@
"Other"
],
"summary": "Link check (beta)",
"operationId": "LinkCheckResponse",
"operationId": "LinkCheck",
"parameters": [
{
"type": "string",
"description": "Database ID",
"description": "Message database ID",
"name": "ID",
"in": "path",
"required": true
},
{
"type": "boolean",
"default": false,
"type": "string",
"default": "false",
"x-go-name": "Follow",
"description": "Follow redirects",
"name": "follow",
"in": "query"
@ -223,7 +224,7 @@
"parameters": [
{
"type": "string",
"description": "Database ID",
"description": "Message database ID",
"name": "ID",
"in": "path",
"required": true
@ -323,7 +324,7 @@
},
"/api/v1/message/{ID}/release": {
"post": {
"description": "Release a message via a pre-configured external SMTP server..",
"description": "Release a message via a pre-configured external SMTP server. This is only enabled if message relaying has been configured.",
"consumes": [
"application/json"
],
@ -338,24 +339,20 @@
"message"
],
"summary": "Release message",
"operationId": "Release",
"operationId": "ReleaseMessage",
"parameters": [
{
"type": "string",
"description": "Database ID",
"description": "Message database ID",
"name": "ID",
"in": "path",
"required": true
},
{
"description": "Array of email addresses to release message to",
"name": "to",
"name": "Body",
"in": "body",
"required": true,
"schema": {
"description": "Array of email addresses to release message to",
"type": "object",
"$ref": "#/definitions/ReleaseMessageRequest"
"$ref": "#/definitions/releaseMessageRequestBody"
}
}
],
@ -428,13 +425,10 @@
"operationId": "SetReadStatus",
"parameters": [
{
"description": "Database IDs to update",
"name": "ids",
"name": "Body",
"in": "body",
"schema": {
"description": "Database IDs to update",
"type": "object",
"$ref": "#/definitions/SetReadStatusRequest"
"$ref": "#/definitions/setReadStatusRequestBody"
}
}
],
@ -448,7 +442,7 @@
}
},
"delete": {
"description": "If no IDs are provided then all messages are deleted.",
"description": "Delete individual or all messages. If no IDs are provided then all messages are deleted.",
"consumes": [
"application/json"
],
@ -463,15 +457,12 @@
"messages"
],
"summary": "Delete messages",
"operationId": "Delete",
"operationId": "DeleteMessages",
"parameters": [
{
"description": "Database IDs to delete",
"name": "ids",
"name": "Body",
"in": "body",
"schema": {
"description": "Database IDs to delete",
"type": "object",
"$ref": "#/definitions/DeleteRequest"
}
}
@ -534,7 +525,7 @@
}
},
"delete": {
"description": "Deletes messages matching a search.",
"description": "Delete all messages matching a search.",
"produces": [
"application/json"
],
@ -546,7 +537,7 @@
"messages"
],
"summary": "Delete messages by search",
"operationId": "MessagesSummary",
"operationId": "DeleteSearch",
"parameters": [
{
"type": "string",
@ -580,7 +571,7 @@
"tags"
],
"summary": "Get all current tags",
"operationId": "SetTags",
"operationId": "GetTags",
"responses": {
"200": {
"$ref": "#/responses/ArrayResponse"
@ -591,7 +582,7 @@
}
},
"put": {
"description": "To remove all tags from a message, pass an empty tags array.",
"description": "This will overwrite any existing tags for selected message database IDs. To remove all tags from a message, pass an empty tags array.",
"consumes": [
"application/json"
],
@ -609,14 +600,10 @@
"operationId": "SetTags",
"parameters": [
{
"description": "Database IDs to update",
"name": "ids",
"name": "Body",
"in": "body",
"required": true,
"schema": {
"description": "Database IDs to update",
"type": "object",
"$ref": "#/definitions/SetTagsRequest"
"$ref": "#/definitions/setTagsRequestBody"
}
}
],
@ -807,15 +794,19 @@
"type": "object",
"properties": {
"ids": {
"description": "ids\nin:body",
"description": "Array of message database IDs",
"type": "array",
"items": {
"type": "string"
},
"x-go-name": "IDs"
"x-go-name": "IDs",
"example": [
"5dec4247-812e-4b77-9101-e25ad406e9ea",
"8ac66bbc-2d9a-4c41-ad99-00aa75fa674e"
]
}
},
"x-go-name": "deleteRequest",
"x-go-name": "deleteMessagesRequestBody",
"x-go-package": "github.com/axllent/mailpit/server/apiv1"
},
"HTMLCheckResponse": {
@ -1188,6 +1179,10 @@
"type": "integer",
"format": "int64"
},
"Snippet": {
"description": "Message snippet includes up to 250 characters",
"type": "string"
},
"Subject": {
"description": "Email subject",
"type": "string"
@ -1214,7 +1209,7 @@
"type": "object",
"properties": {
"messages": {
"description": "Messages summary\nin:body",
"description": "Messages summary\nin: body",
"type": "array",
"items": {
"$ref": "#/definitions/MessageSummary"
@ -1256,67 +1251,6 @@
},
"x-go-package": "github.com/axllent/mailpit/server/apiv1"
},
"ReleaseMessageRequest": {
"description": "Release request",
"type": "object",
"properties": {
"to": {
"description": "To\nin:body",
"type": "array",
"items": {
"type": "string"
},
"x-go-name": "To"
}
},
"x-go-name": "releaseMessageRequest",
"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"
},
"WebUIConfiguration": {
"description": "Response includes global web UI settings",
"type": "object",
@ -1350,6 +1284,89 @@
},
"x-go-name": "webUIConfiguration",
"x-go-package": "github.com/axllent/mailpit/server/apiv1"
},
"releaseMessageRequestBody": {
"description": "Release request",
"type": "object",
"required": [
"to"
],
"properties": {
"to": {
"description": "Array of email addresses to relay the message to",
"type": "array",
"items": {
"type": "string"
},
"x-go-name": "To",
"example": [
"user1@example.com",
"user2@example.com"
]
}
},
"x-go-package": "github.com/axllent/mailpit/server/apiv1"
},
"setReadStatusRequestBody": {
"description": "Set read status request",
"type": "object",
"properties": {
"ids": {
"description": "Array of message database IDs",
"type": "array",
"items": {
"type": "string"
},
"x-go-name": "IDs",
"example": [
"5dec4247-812e-4b77-9101-e25ad406e9ea",
"8ac66bbc-2d9a-4c41-ad99-00aa75fa674e"
]
},
"read": {
"description": "Read status",
"type": "boolean",
"default": false,
"x-go-name": "Read",
"example": true
}
},
"x-go-package": "github.com/axllent/mailpit/server/apiv1"
},
"setTagsRequestBody": {
"description": "Set tags request",
"type": "object",
"required": [
"tags",
"ids"
],
"properties": {
"ids": {
"description": "Array of message database IDs",
"type": "array",
"items": {
"type": "string"
},
"x-go-name": "IDs",
"example": [
"5dec4247-812e-4b77-9101-e25ad406e9ea",
"8ac66bbc-2d9a-4c41-ad99-00aa75fa674e"
]
},
"tags": {
"description": "Array of tag names to set",
"type": "array",
"items": {
"type": "string"
},
"x-go-name": "Tags",
"example": [
"Tag 1",
"Tag 2"
]
}
},
"x-go-package": "github.com/axllent/mailpit/server/apiv1"
}
},
"responses": {
@ -1363,23 +1380,27 @@
}
},
"BinaryResponse": {
"description": "Binary data response inherits the attachment's content type"
"description": "Binary data response inherits the attachment's content type",
"schema": {
"type": "string"
}
},
"ErrorResponse": {
"description": "Error response"
"description": "Error response",
"schema": {
"type": "string"
}
},
"HTMLResponse": {
"description": "HTML response"
"description": "HTML response",
"schema": {
"type": "string"
}
},
"InfoResponse": {
"description": "Application information",
"schema": {
"$ref": "#/definitions/AppInformation"
},
"headers": {
"Body": {
"description": "Application information"
}
}
},
"MessagesSummaryResponse": {
@ -1389,20 +1410,21 @@
}
},
"OKResponse": {
"description": "Plain text \"ok\" response"
"description": "Plain text \"ok\" response",
"schema": {
"type": "string"
}
},
"TextResponse": {
"description": "Plain text response"
"description": "Plain text response",
"schema": {
"type": "string"
}
},
"WebUIConfigurationResponse": {
"description": "Web UI configuration",
"schema": {
"$ref": "#/definitions/WebUIConfiguration"
},
"headers": {
"Body": {
"description": "Web UI configuration settings"
}
}
}
}