API 文档：GraphQL 接口 - Query { user(id: $id) { name email } }

此文档详细描述了 GraphQL 接口 Query 的使用，包括请求格式、参数说明、认证方式、响应结构、状态码及操作示例。

接口说明

此接口用于查询特定用户的姓名和电子邮件地址，接口通过用户的唯一标识符 id 来进行查询。

请求格式

GraphQL 请求需要通过 HTTP POST 方法发送，且请求的 Content-Type 必须为 application/json。请求的查询体中应该包含 GraphQL 查询语句和变量。

• HTTP 方法: POST
• URL: /graphql

请求头 (Headers)

如果接口需要认证，通常需要在请求头中传递身份验证令牌：

Authorization: Bearer <your_token_here>

示例：

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI

请求参数

1. id (必填): 用户的唯一标识 (ID)。
   • 类型: String 或 Int
   • 描述: 需要查询的用户的唯一 ID。

GraphQL 查询

以下为 GraphQL 查询的请求示例：

query GetUser($id: ID!) {
  user(id: $id) {
    name
    email
  }
}

• 变量: $id 用于传递用户的 ID，用 JSON 格式传递。

请求体示例

请求体应传递 GraphQL 查询和相应变量，示例如下：

{
  "query": "query GetUser($id: ID!) { user(id: $id) { name email } }",
  "variables": {
    "id": "12345"
  }
}

响应结构

GraphQL 响应的基本结构如下：

• 字段:
  • data: 包含查询的结果数据。
  • errors: 若查询出现错误，则会包含错误信息。

示例返回格式：

成功响应

{
  "data": {
    "user": {
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  }
}

错误响应

{
  "errors": [
    {
      "message": "User not found",
      "locations": [
        {
          "line": 1,
          "column": 3
        }
      ],
      "path": ["user"]
    }
  ]
}

状态码

GraphQL 通常统一使用 HTTP 200 状态码表示请求成功发出，以下是常见状态码及其含义：

• 200 OK: 请求成功，GraphQL 查询已成功处理。
• 401 Unauthorized: 缺少或提供了无效的认证令牌。
• 403 Forbidden: 已通过认证，但没有执行该操作的权限。
• 404 Not Found: 未找到指定的用户数据。
• 500 Internal Server Error: 服务器内部错误。

使用示例

Curl 示例

以下是通过 curl 发送请求的示例：

curl -X POST https://api.example.com/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your_token_here>" \
-d '{
  "query": "query GetUser($id: ID!) { user(id: $id) { name email } }",
  "variables": {
    "id": "12345"
  }
}'

JavaScript Axios 示例

const axios = require('axios');

const query = `
  query GetUser($id: ID!) {
    user(id: $id) {
      name
      email
    }
  }
`;

const variables = { id: "12345" };

axios.post(
  'https://api.example.com/graphql',
  {
    query,
    variables
  },
  {
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Bearer <your_token_here>',
    }
  }
).then(response => {
  console.log(response.data);
}).catch(error => {
  console.error(error.response.data);
});

注意事项

• 确保提供有效的认证令牌 (如适用)。
• GraphQL 查询语句和变量区分大小写。
• 如果查询的数据很敏感，务必使用 HTTPS 传输数据。

此 API 文档提供了一个完整的参考案例用于查询用户的基本信息，你可以根据项目需求扩展其他参数或功能。

以下是为POST /api/v1/products 生成的详细API文档：

API 文档：创建产品

概述

该接口允许客户端创建一个新的产品。客户端需要发送必要的产品数据，服务器将处理创建请求，并将成功创建的产品信息返回给客户端。

基本信息

• URL: /api/v1/products
• 方法: POST
• 认证: 需要使用 Bearer Token (基于OAuth2.0)
• 内容类型: application/json

请求格式

Headers

请求体参数

请求体示例

{
  "name": "Wireless Mouse",
  "description": "A lightweight wireless mouse",
  "price": 29.99,
  "stock_quantity": 150,
  "category_id": 4,
  "image_urls": [
    "https://example.com/products/mouse1.jpg",
    "https://example.com/products/mouse2.jpg"
  ]
}

响应

响应结构

成功的响应将返回包含新创建的产品详细信息的JSON对象：

状态码

响应示例

成功响应（201 Created）

{
  "id": 101,
  "name": "Wireless Mouse",
  "description": "A lightweight wireless mouse",
  "price": 29.99,
  "stock_quantity": 150,
  "category_id": 4,
  "image_urls": [
    "https://example.com/products/mouse1.jpg",
    "https://example.com/products/mouse2.jpg"
  ],
  "created_at": "2023-10-25T12:34:56Z",
  "updated_at": "2023-10-25T12:34:56Z"
}

错误响应（400 Bad Request）

{
  "error": "Invalid request",
  "message": "The field 'price' is required and must be a positive number."
}

错误响应（401 Unauthorized）

{
  "error": "Unauthorized",
  "message": "A valid Bearer token is required for authentication."
}

错误响应（404 Not Found）

{
  "error": "Not Found",
  "message": "The category with id '4' does not exist."
}

使用示例

CURL 示例

curl -X POST https://example.com/api/v1/products \
-H "Authorization: Bearer <your_token>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Wireless Mouse",
  "description": "A lightweight wireless mouse",
  "price": 29.99,
  "stock_quantity": 150,
  "category_id": 4,
  "image_urls": [
    "https://example.com/products/mouse1.jpg",
    "https://example.com/products/mouse2.jpg"
  ]
}'

JavaScript (Axios) 示例

const axios = require('axios');

const data = {
  name: "Wireless Mouse",
  description: "A lightweight wireless mouse",
  price: 29.99,
  stock_quantity: 150,
  category_id: 4,
  image_urls: [
    "https://example.com/products/mouse1.jpg",
    "https://example.com/products/mouse2.jpg"
  ]
};

axios.post('https://example.com/api/v1/products', data, {
  headers: {
    'Authorization': 'Bearer <your_token>',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log('Product created:', response.data);
})
.catch(error => {
  console.error('Error creating product:', error.response.data);
});

以上为POST /api/v1/products的详细API文档。