Merge branch 'feature/swagger' into develop

axllent · Oct 16, 2023 · 506400b · 506400b
2 parents 0e01b9f + 4c3e073
commit 506400b
Show file tree

Hide file tree

Showing 7 changed files with 464 additions and 216 deletions.
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -16,7 +16,8 @@ jobs:
       with:
         go-version: ${{ matrix.go-version }}
     - uses: actions/checkout@v4
-    - uses: actions/cache@v3
+    - name: Run Go tests
+      uses: actions/cache@v3
       with:
         path: |
           ~/.cache/go-build
@@ -25,12 +26,19 @@ jobs:
         restore-keys: |
           ${{ runner.os }}-go-
     - run: go test ./internal/storage ./server ./internal/tools ./internal/tools/html2text -v
-    - run: go test ./internal/storage -bench=.
+    - run: go test ./internal/storage ./internal/tools/html2text -bench=.
 
     # build the assets
-    - uses: actions/setup-node@v3
+    - name: Build web UI
+      uses: actions/setup-node@v3
       with:
         node-version: 18
         cache: 'npm'
     - run: npm install
     - run: npm run package
+
+    # validate the swagger file
+    - name: Validate OpenAPI definition
+      uses: char0n/swagger-editor-validate@v1
+      with:
+        definition-file: server/ui/api/v1/swagger.json
diff --git a/internal/tools/html2text/html2text.go b/internal/tools/html2text/html2text.go
@@ -6,6 +6,7 @@ import (
 	"log"
 	"regexp"
 	"strings"
+	"unicode"
 
 	"golang.org/x/net/html"
 )
@@ -67,6 +68,15 @@ func extract(node *html.Node, buff *bytes.Buffer, includeLinks bool) {
 func clean(text string) string {
 	// replace \uFEFF with space, see https://github.com/golang/go/issues/42274#issuecomment-1017258184
 	text = strings.ReplaceAll(text, string('\uFEFF'), " ")
+
+	// remove non-printable characters
+	text = strings.Map(func(r rune) rune {
+		if unicode.IsPrint(r) {
+			return r
+		}
+		return []rune(" ")[0]
+	}, text)
+
 	text = re.ReplaceAllString(text, " ")
 	return strings.TrimSpace(text)
 }
diff --git a/internal/tools/html2text/html2text_test.go b/internal/tools/html2text/html2text_test.go
diff --git a/server/apiv1/api.go b/server/apiv1/api.go
@@ -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

diff --git a/server/apiv1/structs.go b/server/apiv1/structs.go
@@ -22,17 +22,14 @@ 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"`
 
 	// All current tags
 	Tags []string `json:"tags"`
 
 	// Messages summary
-	// in:body
+	// in: body
 	Messages []storage.MessageSummary `json:"messages"`
 }