chore: add api docs (usememos#1965)

api/v1/auth.go

@@ -33,6 +33,7 @@ type SignUp struct {
 }
 
 func (s *APIV1Service) registerAuthRoutes(g *echo.Group) {
+	// POST /auth/signin - Sign in.
 	g.POST("/auth/signin", func(c echo.Context) error {
 		ctx := c.Request().Context()
 		signin := &SignIn{}
@@ -67,6 +68,7 @@ func (s *APIV1Service) registerAuthRoutes(g *echo.Group) {
 		return c.JSON(http.StatusOK, user)
 	})
 
+	// POST /auth/signin/sso - Sign in with SSO
 	g.POST("/auth/signin/sso", func(c echo.Context) error {
 		ctx := c.Request().Context()
 		signin := &SSOSignIn{}
@@ -153,6 +155,7 @@ func (s *APIV1Service) registerAuthRoutes(g *echo.Group) {
 		return c.JSON(http.StatusOK, user)
 	})
 
+	// POST /auth/signup - Sign up a new user.
 	g.POST("/auth/signup", func(c echo.Context) error {
 		ctx := c.Request().Context()
 		signup := &SignUp{}
@@ -218,6 +221,7 @@ func (s *APIV1Service) registerAuthRoutes(g *echo.Group) {
 		return c.JSON(http.StatusOK, user)
 	})
 
+	// POST /auth/signout - Sign out.
 	g.POST("/auth/signout", func(c echo.Context) error {
 		auth.RemoveTokensAndCookies(c)
 		return c.JSON(http.StatusOK, true)

api/v1/http_getter.go

@@ -10,6 +10,7 @@ import (
 )
 
 func (*APIV1Service) registerGetterPublicRoutes(g *echo.Group) {
+	// GET /get/httpmeta?url={url} - Get website meta.
 	g.GET("/get/httpmeta", func(c echo.Context) error {
 		urlStr := c.QueryParam("url")
 		if urlStr == "" {
@@ -26,6 +27,7 @@ func (*APIV1Service) registerGetterPublicRoutes(g *echo.Group) {
 		return c.JSON(http.StatusOK, htmlMeta)
 	})
 
+	// GET /get/image?url={url} - Get image.
 	g.GET("/get/image", func(c echo.Context) error {
 		urlStr := c.QueryParam("url")
 		if urlStr == "" {

api/v1/user.go

@@ -129,6 +129,7 @@ func (update UpdateUserRequest) Validate() error {
 }
 
 func (s *APIV1Service) registerUserRoutes(g *echo.Group) {
+	// POST /user - Create a new user.
 	g.POST("/user", func(c echo.Context) error {
 		ctx := c.Request().Context()
 		userID, ok := c.Get(getUserIDContextKey()).(int)
@@ -184,6 +185,7 @@ func (s *APIV1Service) registerUserRoutes(g *echo.Group) {
 		return c.JSON(http.StatusOK, userMessage)
 	})
 
+	// GET /user - List all users.
 	g.GET("/user", func(c echo.Context) error {
 		ctx := c.Request().Context()
 		list, err := s.Store.ListUsers(ctx, &store.FindUser{})
@@ -202,7 +204,7 @@ func (s *APIV1Service) registerUserRoutes(g *echo.Group) {
 		return c.JSON(http.StatusOK, userMessageList)
 	})
 
-	// GET /api/user/me is used to check if the user is logged in.
+	// GET /user/me - Get current user.
 	g.GET("/user/me", func(c echo.Context) error {
 		ctx := c.Request().Context()
 		userID, ok := c.Get(getUserIDContextKey()).(int)
@@ -233,6 +235,7 @@ func (s *APIV1Service) registerUserRoutes(g *echo.Group) {
 		return c.JSON(http.StatusOK, userMessage)
 	})
 
+	// GET /user/:id - Get user by id.
 	g.GET("/user/:id", func(c echo.Context) error {
 		ctx := c.Request().Context()
 		id, err := strconv.Atoi(c.Param("id"))
@@ -255,6 +258,7 @@ func (s *APIV1Service) registerUserRoutes(g *echo.Group) {
 		return c.JSON(http.StatusOK, userMessage)
 	})
 
+	// PUT /user/:id - Update user by id.
 	g.PATCH("/user/:id", func(c echo.Context) error {
 		ctx := c.Request().Context()
 		userID, err := strconv.Atoi(c.Param("id"))
@@ -339,6 +343,7 @@ func (s *APIV1Service) registerUserRoutes(g *echo.Group) {
 		return c.JSON(http.StatusOK, userMessage)
 	})
 
+	// DELETE /user/:id - Delete user by id.
 	g.DELETE("/user/:id", func(c echo.Context) error {
 		ctx := c.Request().Context()
 		currentUserID, ok := c.Get(getUserIDContextKey()).(int)

docs/api/auth.md

@@ -0,0 +1,107 @@
+# Authentication APIs
+
+## Sign In
+
+```
+POST /api/v1/auth/signin
+```
+
+**Request Body**
+
+```json
+{
+  "username": "john",
+  "password": "password123"
+}
+```
+
+**Response**
+
+```json
+{
+  "id": 123,
+  "username": "john",
+  "nickname": "John"
+  // other user fields
+}
+```
+
+**Status Codes**
+
+- 200: Sign in success
+- 400: Invalid request
+- 401: Incorrect credentials
+- 403: User banned
+- 500: Internal server error
+
+## SSO Sign In
+
+```
+POST /api/v1/auth/signin/sso
+```
+
+**Request Body**
+
+```json
+{
+  "identityProviderId": 123,
+  "code": "abc123",
+  "redirectUri": "https://example.com/callback"
+}
+```
+
+**Response**
+
+Same as **Sign In**
+
+**Status Codes**
+
+- 200: Success
+- 400: Invalid request
+- 401: Authentication failed
+- 403: User banned
+- 404: Identity provider not found
+- 500: Internal server error
+
+## Sign Up
+
+```
+POST /api/v1/auth/signup
+```
+
+**Request Body**
+
+```json
+{
+  "username": "mary",
+  "password": "password456"
+}
+```
+
+**Response**
+
+Same as **Sign In**
+
+**Status Codes**
+
+- 200: Sign up success
+- 400: Invalid request
+- 401: Sign up disabled
+- 500: Internal server error
+
+## Sign Out
+
+```
+POST /api/v1/auth/signout
+```
+
+**Response**
+
+```
+true
+```
+
+**Status Codes**
+
+- 200: Success
+- 500: Internal server error

docs/api/how-to.md

@@ -0,0 +1,44 @@
+# Guide to Access Memos API with OpenID
+
+Memos API supports using OpenID as the user identifier to access the API.
+
+## What is OpenID
+
+OpenID is a unique identifier assigned by Memos system to each user.
+
+When a user registers or logs in via third-party OAuth through Memos system, the OpenID will be generated automatically.
+
+## How to Get User's OpenID
+
+You can get a user's OpenID through:
+
+- User checks the personal profile page in Memos system
+- Calling Memos API to get user details
+- Retrieving from login API response after successful login
+
+Example:
+
+```
+// GET /api/v1/user/me
+
+{
+  "id": 123,
+  "username": "john",
+  "openId": "8613E04B4FA6603883F05A5E0A5E2517",
+  ...
+}
+```
+
+## How to Use OpenID to Access API
+
+You can access the API on behalf of the user by appending `?openId=xxx` parameter to the API URL.
+
+For example:
+
+```
+curl 'https://demo.usememos.com/api/v1/memo?openId=8613E04B4FA6603883F05A5E0A5E2517' -H 'Content-Type: application/json' --data-raw '{"content":"Hello world!"}'
+```
+
+The above request will create a Memo under the user with OpenID `8613E04B4FA6603883F05A5E0A5E2517`.
+
+OpenID can be used in any API that requires user identity.

docs/api/memo-relation.md

@@ -0,0 +1,67 @@
+# Memo Relation APIs
+
+## Create Memo Relation
+
+```
+POST /api/v1/memo/:memoId/relation
+```
+
+**Request Body**
+
+```json
+{
+  "relatedMemoId": 456,
+  "type": "REFERENCE"
+}
+```
+
+**Response**
+
+```json
+{
+  "memoId": 123,
+  "relatedMemoId": 456,
+  "type": "REFERENCE"
+}
+```
+
+**Status Codes**
+
+- 200: OK
+- 400: Invalid request
+- 500: Internal server error
+
+## Get Memo Relations
+
+```
+GET /api/v1/memo/:memoId/relation
+```
+
+**Response**
+
+```json
+[
+  {
+    "memoId": 123,
+    "relatedMemoId": 456,
+    "type": "REFERENCE"
+  }
+]
+```
+
+**Status Codes**
+
+- 200: OK
+- 500: Internal server error
+
+## Delete Memo Relation
+
+```
+DELETE /api/v1/memo/:memoId/relation/:relatedMemoId/type/:relationType
+```
+
+**Status Codes**
+
+- 200: Deleted
+- 400: Invalid request
+- 500: Internal server error

docs/api/memo-resource.md

@@ -0,0 +1,65 @@
+# Memo Resource APIs
+
+## Bind Resource to Memo
+
+```
+POST /api/v1/memo/:memoId/resource
+```
+
+**Request Body**
+
+```json
+{
+  "resourceId": 123
+}
+```
+
+**Response**
+
+```
+true
+```
+
+**Status Codes**
+
+- 200: OK
+- 400: Invalid request
+- 401: Unauthorized
+- 404: Memo/Resource not found
+- 500: Internal server error
+
+## Get Memo Resources
+
+```
+GET /api/v1/memo/:memoId/resource
+```
+
+**Response**
+
+```json
+[
+  {
+    "id": 123,
+    "filename": "example.png"
+    // other resource fields
+  }
+]
+```
+
+**Status Codes**
+
+- 200: OK
+- 500: Internal server error
+
+## Unbind Resource from Memo
+
+```
+DELETE /api/v1/memo/:memoId/resource/:resourceId
+```
+
+**Status Codes**
+
+- 200: OK
+- 401: Unauthorized
+- 404: Memo/Resource not found
+- 500: Internal server error