feiniao-site-node/docs/api-docs.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "飞鸟农业API文档",
    "version": "1.0.0",
    "description": "飞鸟农业平台后端API接口文档"
  },
  "servers": [
    {
      "url": "http://localhost:3000",
      "description": "开发环境"
    }
  ],
  "paths": {
    "/admin/articles": {
      "get": {
        "tags": [
          "Articles"
        ],
        "summary": "GetArticles",
        "description": "获取文章列表，支持分页和多条件筛选",
        "parameters": [
          {
            "name": "currentPage=1",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "当前页码，默认为1"
          },
          {
            "name": "pageSize=10",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "每页显示数量，默认为10"
          },
          {
            "name": "title",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "标题搜索关键词（模糊匹配）"
          },
          {
            "name": "cropIds",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string|array"
            },
            "description": "作物筛选ID，支持逗号分隔的多个ID或数组形式"
          },
          {
            "name": "categoryId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "用户分类ID，根据用户传递的category参数值进行精确匹配"
          },
          {
            "name": "isRecommended",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "推荐筛选，0-非推荐文章，1-推荐文章"
          }
        ],
        "responses": {
          "200": {
            "description": "成功响应",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "400": {
            "description": "请求参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "404": {
            "description": "资源未找到",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "500": {
            "description": "服务器内部错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Articles"
        ],
        "summary": "CreateArticle",
        "description": "创建新的文章，支持富文本内容和图片",
        "parameters": [
          {
            "name": "title",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "文章标题（必填，1-500字符）"
          },
          {
            "name": "content",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "文章内容（必填，富文本格式，最大5MB）"
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "文章类型"
          },
          {
            "name": "img",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "文章图片URL"
          },
          {
            "name": "date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "date"
            },
            "description": "文章发布日期"
          },
          {
            "name": "author",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "作者"
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "用户分类ID（用户传递的参数）"
          },
          {
            "name": "crop",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "作物分类ID"
          },
          {
            "name": "isRecommended=0",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "是否推荐，0-不推荐，1-推荐"
          },
          {
            "name": "subtitle",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "副标题（最大200字符）"
          },
          {
            "name": "seoKeyword",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "SEO关键词"
          },
          {
            "name": "seoDescription",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "SEO描述"
          }
        ],
        "responses": {
          "200": {
            "description": "成功响应",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "400": {
            "description": "请求参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "404": {
            "description": "资源未找到",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "500": {
            "description": "服务器内部错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Article"
              }
            }
          }
        }
      }
    },
    "/admin/articles/:id": {
      "get": {
        "tags": [
          "Articles"
        ],
        "summary": "GetArticleById",
        "description": "根据文章ID获取文章详细信息",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "文章ID（路径参数）"
          }
        ],
        "responses": {
          "200": {
            "description": "成功响应",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "400": {
            "description": "请求参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "404": {
            "description": "资源未找到",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "500": {
            "description": "服务器内部错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Articles"
        ],
        "summary": "DeleteArticle",
        "description": "根据文章ID删除文章",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "文章ID（路径参数）"
          }
        ],
        "responses": {
          "200": {
            "description": "成功响应",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "400": {
            "description": "请求参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "404": {
            "description": "资源未找到",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "500": {
            "description": "服务器内部错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Articles"
        ],
        "summary": "UpdateArticle",
        "description": "根据文章ID更新文章信息",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "文章ID（路径参数）"
          },
          {
            "name": "title",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "文章标题（1-500字符）"
          },
          {
            "name": "content",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "文章内容（富文本格式，最大5MB）"
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "文章类型"
          },
          {
            "name": "img",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "文章图片URL"
          },
          {
            "name": "date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "date"
            },
            "description": "文章发布日期"
          },
          {
            "name": "author",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "作者"
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "用户分类ID"
          },
          {
            "name": "crop",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "作物分类ID"
          },
          {
            "name": "isRecommended",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "是否推荐，0-不推荐，1-推荐"
          },
          {
            "name": "subtitle",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "副标题（最大200字符）"
          },
          {
            "name": "seoKeyword",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "SEO关键词"
          },
          {
            "name": "seoDescription",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "SEO描述"
          }
        ],
        "responses": {
          "200": {
            "description": "成功响应",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "400": {
            "description": "请求参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "404": {
            "description": "资源未找到",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "500": {
            "description": "服务器内部错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Article"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Article": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "文章ID"
          },
          "title": {
            "type": "string",
            "description": "文章标题"
          },
          "subtitle": {
            "type": "string",
            "description": "文章副标题"
          },
          "content": {
            "type": "string",
            "description": "文章内容"
          },
          "type": {
            "type": "integer",
            "description": "文章类型"
          },
          "img": {
            "type": "string",
            "description": "文章图片URL"
          },
          "date": {
            "type": "string",
            "format": "date-time",
            "description": "文章日期"
          },
          "author": {
            "type": "string",
            "description": "作者"
          },
          "category": {
            "type": "integer",
            "description": "用户分类ID"
          },
          "crop": {
            "type": "integer",
            "description": "作物分类ID"
          },
          "isRecommended": {
            "type": "integer",
            "enum": [
              0,
              1
            ],
            "description": "是否推荐"
          },
          "seoKeyword": {
            "type": "string",
            "description": "SEO关键词"
          },
          "seoDescription": {
            "type": "string",
            "description": "SEO描述"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "创建时间"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "更新时间"
          },
          "cropInfo": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "description": "作物ID"
              },
              "name": {
                "type": "string",
                "description": "作物名称"
              },
              "level": {
                "type": "integer",
                "description": "作物层级"
              },
              "parentId": {
                "type": "integer",
                "description": "父级作物ID"
              }
            }
          }
        }
      },
      "ApiResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "boolean",
            "description": "请求状态"
          },
          "message": {
            "type": "string",
            "description": "响应消息"
          },
          "data": {
            "type": "object",
            "description": "响应数据"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "错误信息"
          }
        }
      }
    }
  }
}