接口名称

接口描述

详细描述这个接口的功能、使用场景和注意事项。

OpenAPI Specification

openapi: 3.0.1
info:
  title: ''
  version: 1.0.0
paths:
  /srv/:
    get:  # 或 post
      summary: 接口简介（一行描述）
      description: |
        接口详细说明...
        - 使用场景 1
        - 使用场景 2
      tags:
        - 模块名称
      parameters:  # GET 请求使用 parameters
        - name: a
          in: query
          description: action 参数
          required: false
          example: your_action_name
          schema:
            type: string
        - name: f
          in: query
          description: 业务模块
          required: false
          example: behalo
          schema:
            type: string
        - name: id
          in: query
          description: 参数描述
          required: true  # true=必填，false=可选
          example: 123
          schema:
            type: integer
      requestBody:  # POST 请求使用 requestBody
        content:
          application/x-www-form-urlencoded:  # 或 application/json
            schema:
              type: object
              required:
                - course_id
                - quantity
              properties:
                course_id:
                  type: integer
                  description: 课程ID
                  example: 1
                quantity:
                  type: integer
                  description: 数量
                  example: 1
      responses:
        '200':
          description: 成功返回
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 0=失败，1=成功
                  msg:
                    type: string
                    description: 错误信息
                  data:
                    type: object
                    description: 返回数据
                    properties:
                      id:
                        type: integer
                        description: 数据ID
                      name:
                        type: string
                        description: 名称
                      items:
                        type: array
                        description: 列表数据
                        items:
                          type: object
                          properties:
                            item_id:
                              type: integer
                              description: 项目ID
                            item_name:
                              type: string
                              description: 项目名称

使用示例

GET 请求示例

import { getYourAPINameAPI } from '@/api/yourModule'

const { code, data } = await getYourAPINameAPI({
  id: 123,
  page: 1,
  limit: 10
})

if (code === 1) {
  console.log('成功:', data)
}

POST 请求示例

import { createYourResourceAPI } from '@/api/yourModule'

const { code, data } = await createYourResourceAPI({
  course_id: 1,
  quantity: 2
})

if (code === 1) {
  console.log('创建成功:', data)
}

注意事项

• 权限要求: 说明是否需要登录、特殊权限等
• 限流规则: 说明接口调用频率限制
• 错误码: 列出常见的错误码及含义
• 兼容性: 说明版本兼容性要求

相关接口

• 相关接口1
• 相关接口2

更新记录

• 2026-01-29: 初始版本，创建接口