YourSelfHosted/memos
1
0
Fork 0
mirror of https://github.com/usememos/memos.git synced 2025-06-05 22:09:59 +02:00
Code Issues Packages Projects Releases Wiki Activity

chore: update api v1 docs (#2117)

Browse Source 
* chore: update apiv1 docs

* chore: update
This commit is contained in:
boojack
2023-08-09 22:30:27 +08:00
committed by GitHub
parent 4491c75135
commit 35f2d399e2
30 changed files with 367 additions and 1166 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
scripts/gen-api-v1-docs.sh Executable file
View File

@ -0,0 +1,108 @@
#!/bin/bash
# This script generates API documentation using swaggo/swag
# For more details, check the docs:
# * https://usememos.com/docs/contribution/development
# * https://github.com/usememos/memos/blob/main/docs/api/documentation.md
# Requirements:
# * go
# swag is configured via gen-api-v1-docs.cfg file.
# Usage:
# chmod +x ./scripts/gen-api-v1-docs.sh
# ./scripts/gen-api-v1-docs.sh
find_repo_root() {
# Usage: find_repo_root <file_at_root> <dir1> <dir2> ...
local looking_for="${1:-".gitignore"}"
shift
local default_dirs=("." "../")
local dirs=("${@:-${default_dirs[@]}}")
for dir in "${dirs[@]}"; do
if [ -f "$dir/$looking_for" ]; then
echo $(realpath "$dir")
return
fi
done
}
find_binary() {
# Usage: find_binary <binary> <dir1> <dir2> ...
local looking_for="$1"
shift
local default_dirs=(".")
local binary=$(command -v $looking_for)
if [ ! -z "$binary" ]; then
echo "$binary"
return
fi
local dirs=("${@:-${default_dirs[@]}}")
for dir in "${dirs[@]}"; do
if [ -f "$dir/$looking_for" ]; then
echo $(realpath "$dir")/$looking_for
return
fi
done
}
repo_root=$(find_repo_root)
if [ -z "$repo_root" ]; then
echo -e "\033[0;31mRepository root not found! Exiting.\033[0m"
exit 1
else
echo -e "Repository root: \033[0;34m$repo_root\033[0m"
fi
cd $repo_root
echo "Parsing gen-api-v1-docs.cfg..."
source "$repo_root/scripts/gen-api-v1-docs.cfg"
echo -e "API directories: \033[0;34m$SWAG_API_DIRS\033[0m"
echo -e "Output directory: \033[0;34m$SWAG_OUTPUT\033[0m"
echo -e "General info: \033[0;34m$SWAG_GENERAL_INFO\033[0m"
if [ -z "$SWAG_API_DIRS" ]; then
echo -e "\033[0;31mAPI directories not set! Exiting.\033[0m"
exit 1
fi
swag=$(find_binary swag "$HOME/go/bin" "$GOPATH/bin")
if [ -z "$swag" ]; then
echo "Swag is not installed. Installing..."
go install github.com/swaggo/swag/cmd/swag@latest
swag=$(find_binary swag "$HOME/go/bin" "$GOPATH/bin")
fi
if [ -z "$swag" ]; then
echo -e "\033[0;31mSwag binary not found! Exiting.\033[0m"
exit 1
fi
echo -e "Swag binary: \033[0;34m$swag\033[0m"
general_info_path=$(dirname "$SWAG_GENERAL_INFO")
if [ ! -d "$general_info_path" ]; then
echo -e "\033[0;31mGeneral info directory does not exist!\033[0m"
exit 1
fi
echo -e "\e[35mFormatting comments via \`swag fmt --dir "$general_info_path,$SWAG_API_DIRS"\`...\e[0m"
$swag fmt --dir "$general_info_path,$SWAG_API_DIRS"
# This is just in case "swag fmt" do something non-conforming to "go fmt"
go_fmt_dirs=$(echo $general_info_path $SWAG_API_DIRS | tr "," " ")
echo -e "\e[35mFormatting code via \`go fmt $go_fmt_dirs\`...\e[0m"
go fmt $go_fmt_dirs
echo -e "\e[35mGenerating Swagger API documentation...\e[0m"
$swag init --output "$SWAG_OUTPUT" --outputTypes "$SWAG_OUTPUT_TYPES" --generalInfo "$SWAG_GENERAL_INFO" --dir "./,$SWAG_API_DIRS"
if [ $? -ne 0 ]; then
echo -e "\033[0;31mFailed to generate Swagger API documentation!\033[0m"
exit 1
fi
echo -e "\033[0;32mSwagger API documentation updated!\033[0m"