mirror of https://github.com/usememos/memos
feat: add SwaggerUI and v1 API docs (#2115)
* - Refactor several API routes from anonymous functions to regular definitions. Required to add parseable documentation comments.
- Add API documentation comments using Swag Declarative Comments Format
- Add echo-swagger to serve Swagger-UI at /api/index.html
- Fix error response from extraneous parameter resourceId to relatedMemoId in DELETE("/memo/:memoId/relation/:relatedMemoId/type/:relationType")
- Add an auto-generated ./docs/api/v1.md for quick reference on repo (generated by swagger-markdown)
- Add auxiliary scripts to generate docs.go and swagger.yaml
* fix: golangci-lint errors
* fix: go fmt flag in swag scripts
pull/2117/head
Lincoln Nogueira
2 years ago
committed by
GitHub
parent
513002ff60
commit
4491c75135
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,113 @@
|
||||
# Documenting the API
|
||||
|
||||
## Principles
|
||||
|
||||
- The documentation is generated by [swaggo/swag](https://github.com/swaggo/swag) from comments in the API code.
|
||||
|
||||
- Documentation is written using [Declarative Comments Format](https://github.com/swaggo/swag#declarative-comments-format).
|
||||
|
||||
- The documentation is generated in the `./api` folder as `docs.go`.
|
||||
|
||||
- [echo-swagger](https://github.com/swaggo/echo-swagger) is used to integrate with Echo framework and serve the documentation with [Swagger-UI](https://swagger.io/tools/swagger-ui/) at `http://memos.host:5230/api/index.html`
|
||||
|
||||
## Updating the documentation
|
||||
|
||||
1. Update or add API-related comments in the code. Make sure to follow the [Declarative Comments Format](https://github.com/swaggo/swag#declarative-comments-format):
|
||||
|
||||
```go
|
||||
// signIn godoc
|
||||
//
|
||||
// @Summary Sign-in to memos.
|
||||
// @Tags auth
|
||||
// @Accept json
|
||||
// @Produce json
|
||||
// @Param body body SignIn true "Sign-in object"
|
||||
// @Success 200 {object} store.User "User information"
|
||||
// @Failure 400 {object} nil "Malformatted signin request"
|
||||
// @Failure 401 {object} nil "Password login is deactivated | Incorrect login credentials, please try again"
|
||||
// @Failure 403 {object} nil "User has been archived with username {username}"
|
||||
// @Failure 500 {object} nil "Failed to find system setting | Failed to unmarshal system setting | Incorrect login credentials, please try again | Failed to generate tokens | Failed to create activity"
|
||||
// @Router /api/v1/auth/signin [POST]
|
||||
func (s *APIV1Service) signIn(c echo.Context) error {
|
||||
...
|
||||
```
|
||||
|
||||
> Sample from [api/v1/auth.go](https://github.com/usememos/memos/tree/main/api/v1/auth.go)
|
||||
> You can check existing comments at [api/v1](https://github.com/usememos/memos/tree/main/api/v1)
|
||||
|
||||
2. Run one of the following provided scripts:
|
||||
|
||||
- Linux: `./scripts/generate-api-documentation.sh` (remember to `chmod +x` the script first)
|
||||
- Windows: `./scripts/generate-api-documentation.ps1`
|
||||
|
||||
> The scripts will install swag if needed (via go install), then run `swag fmt` and `swag init` commands.
|
||||
|
||||
3. That's it! The documentation is updated. You can check it at `http://memos.host:5230/api/index.html`
|
||||
|
||||
### Extra tips
|
||||
|
||||
- If you reference a custom Go struct from outside the API file, use a relative definition, like `store.IdentityProvider`. This works because `./` is passed to swag at `--dir` argument. If swag can't resolve the reference, it will fail.
|
||||
|
||||
- If the API grows or you need to reference some type from another location, remember to update ./scripts/generate-api-documentation.cfg file with the new paths.
|
||||
|
||||
- It's possible to list multiple errors for the same code using enum-like structs, that will show a proper, spec-conformant model with all entries at Swagger-UI. The drawback is that this approach requires a major refactoring and will add a lot of boilerplate code, as there are inconsistencies between API methods error responses.
|
||||
|
||||
```go
|
||||
type signInInternalServerError string
|
||||
|
||||
const signInErrorFailedToFindSystemSetting signInInternalServerError = "Failed to find system setting"
|
||||
const signInErrorFailedToUnmarshalSystemSetting signInInternalServerError = "Failed to unmarshal system setting"
|
||||
const signInErrorIncorrectLoginCredentials signInInternalServerError = "Incorrect login credentials, please try again"
|
||||
const signInErrorFailedToGenerateTokens signInInternalServerError = "Failed to generate tokens"
|
||||
const signInErrorFailedToCreateActivity signInInternalServerError = "Failed to create activity"
|
||||
|
||||
type signInUnauthorized string
|
||||
|
||||
const signInErrorPasswordLoginDeactivated signInUnauthorized = "Password login is deactivated"
|
||||
const signInErrorIncorrectCredentials signInUnauthorized = "Incorrect login credentials, please try again"
|
||||
|
||||
// signIn godoc
|
||||
//
|
||||
// @Summary Sign-in to memos.
|
||||
// @Tags auth
|
||||
// @Accept json
|
||||
// @Produce json
|
||||
// @Param body body SignIn true "Sign-in object"
|
||||
// @Success 200 {object} store.User "User information"
|
||||
// @Failure 400 {object} nil "Malformatted signin request"
|
||||
// @Failure 401 {object} signInUnauthorized
|
||||
// @Failure 403 {object} nil "User has been archived with username {username}"
|
||||
// @Failure 500 {object} signInInternalServerError
|
||||
// @Router /api/v1/auth/signin [POST]
|
||||
func (s *APIV1Service) signIn(c echo.Context) error {
|
||||
...
|
||||
```
|
||||
|
||||
### Step-by-step (no scripts)
|
||||
|
||||
#### Required tools
|
||||
|
||||
```bash
|
||||
# Swag v1.8.12 or newer
|
||||
# Also updates swag if needed
|
||||
$ go install github.com/swaggo/swag/cmd/swag@latest
|
||||
```
|
||||
|
||||
If `$HOME/go/bin` is not in your `PATH`, you can call `swag` directly at `$HOME/go/bin/swag`.
|
||||
|
||||
#### Generate the documentation
|
||||
|
||||
1. Run `swag fmt` to format the comments
|
||||
|
||||
```bash
|
||||
swag fmt --dir ./api/v1 && go fmt
|
||||
```
|
||||
|
||||
2. Run `swag init` to generate the documentation
|
||||
|
||||
```bash
|
||||
cd <project-root>
|
||||
swag init --output api --generalInfo ./server/server.go --dir ./,./api/v1
|
||||
```
|
||||
|
||||
> If the API gets a new version, you'll need to add the file system path to swag's `--dir` parameter.
|
||||
@ -0,0 +1,13 @@
|
||||
# This file is used by generate-api-documentation.ps1 and generate-api-documentation.sh
|
||||
|
||||
# You should list aditional dirs here if the API grows
|
||||
SWAG_API_DIRS=./api/v1
|
||||
|
||||
# Where general API info is documented
|
||||
SWAG_GENERAL_INFO=./server/server.go
|
||||
|
||||
# Possible output files: go (docs.go), json (swagger.json), yaml (swagger.yaml)
|
||||
SWAG_OUTPUT_TYPES=go,yaml
|
||||
|
||||
# Where generated files are outputted
|
||||
SWAG_OUTPUT=./api
|
||||
@ -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 generate-api-documentation.cfg file.
|
||||
|
||||
# Usage:
|
||||
# chmod +x ./scripts/generate-api-documentation.sh
|
||||
# ./scripts/generate-api-documentation.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 generate-api-documentation.cfg..."
|
||||
source "$repo_root/scripts/generate-api-documentation.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"
|
||||
Loading…
Reference in New Issue