add swagger doc to mkdocs/website

.github/workflows/pages.yml

@@ -20,7 +20,7 @@ jobs:
           python-version: 3.x
 
       - name: Install dependencies
-        run: pip install mike mkdocs-material[imaging] mkdocs-minify-plugin
+        run: pip install mike mkdocs-material[imaging] mkdocs-minify-plugin mkdocs-swagger-ui-tag
 
       - name: Publish documentation
         run: mike deploy --push --update-aliases ${{ github.ref_name }} latest

cmd/api_build_tool/main.go

@@ -12,14 +12,18 @@ import (
 	"github.com/swaggo/swag/gen"
 )
 
+var apiRootPath = "/internal/app/api"
+var apiDocPath = "core/assets/doc"
+var apiMkDocPath = "/docs/documentation/rest-api"
+
 // this replaces the call to: swag init --propertyStrategy pascalcase --parseDependency --parseInternal --generalInfo base.go
 func main() {
 	wd, err := os.Getwd() // should be the project root
 	if err != nil {
 		panic(err)
 	}
 
-	apiBasePath := filepath.Join(wd, "/internal/app/api")
+	apiBasePath := filepath.Join(wd, apiRootPath)
 	apis := []string{"v0", "v1"}
 
 	hasError := false
@@ -37,6 +41,15 @@ func main() {
 			logrus.Errorf("failed to generate API docs for %s: %v", apiVersion, err)
 		}
 
+		// copy the latest version of the API docs for mkdocs
+		if apiVersion == apis[len(apis)-1] {
+			if err = copyDocForMkdocs(wd, apiBasePath, apiVersion); err != nil {
+				logrus.Errorf("failed to copy API docs for mkdocs: %v", err)
+			} else {
+				log.Println("Copied API docs " + apiVersion + " for mkdocs")
+			}
+		}
+
 		log.Println("Generated swagger docs for API", apiVersion)
 	}
 
@@ -51,7 +64,7 @@ func generateApi(basePath, apiPath, version string) error {
 		Excludes:            "",
 		MainAPIFile:         "base.go",
 		PropNamingStrategy:  swag.PascalCase,
-		OutputDir:           filepath.Join(basePath, "core/assets/doc"),
+		OutputDir:           filepath.Join(basePath, apiDocPath),
 		OutputTypes:         []string{"json", "yaml"},
 		ParseVendor:         false,
 		ParseDependency:     3,
@@ -68,3 +81,21 @@ func generateApi(basePath, apiPath, version string) error {
 
 	return nil
 }
+
+func copyDocForMkdocs(workingDir, basePath, version string) error {
+	srcPath := filepath.Join(basePath, apiDocPath, fmt.Sprintf("%s_swagger.yaml", version))
+	dstPath := filepath.Join(workingDir, apiMkDocPath, "swagger.yaml")
+
+	// copy the file
+	input, err := os.ReadFile(srcPath)
+	if err != nil {
+		return fmt.Errorf("error while reading swagger doc: %w", err)
+	}
+
+	err = os.WriteFile(dstPath, input, 0644)
+	if err != nil {
+		return fmt.Errorf("error while writing swagger doc: %w", err)
+	}
+
+	return nil
+}

docs/documentation/overview.md

@@ -21,7 +21,7 @@ The configuration portal supports using a database (SQLite, MySQL, MsSQL or Post
 * Support for multiple WireGuard interfaces
 * Peer Expiry Feature
 * Handle route and DNS settings like wg-quick does
-* ~~REST API for management and client deployment~~ (coming soon)
+* REST API for management and client deployment
 
 ## Quick-Start
 

docs/documentation/rest-api/api-doc.md

@@ -0,0 +1 @@
+<swagger-ui src="./swagger.yaml"/>

mkdocs.yml

@@ -4,7 +4,7 @@ site_description: Manage WireGuard Peers and Interface using a beautiful and sim
 site_url: https://wgportal.org/
 repo_name: h44z/wg-portal
 repo_url: https://github.com/h44z/wg-portal
-copyright: Copyright © 2023-2024 WireGuard Portal Project
+copyright: Copyright © 2023-2025 WireGuard Portal Project
 
 extra_css:
   - stylesheets/extra.css
@@ -27,6 +27,7 @@ plugins:
   - social
   - minify:
       minify_html: true
+  - swagger-ui-tag
 
 extra:
   version:
@@ -60,3 +61,4 @@ nav:
           - Building: documentation/getting-started/building.md
           - Docker Container: documentation/getting-started/docker.md
           - Upgrade from V1: documentation/getting-started/upgrade.md
+      - REST API: documentation/rest-api/api-doc.md