跳到主要内容
版本：Next

API接口参考

本文档中引用的文件

目录​

  1. 简介
  2. 认证与权限
  3. 版本控制
  4. 分页与排序
  5. API端点详情
  6. 数据模型
  7. 错误处理
  8. 使用示例

简介​

本接口参考文档详细描述了MyEntityNameController暴露的RESTful API端点。这些API基于IMyEntityNameAppService契约接口和相关DTO定义，提供了对MyEntityName实体的完整CRUD操作，以及导入、导出和克隆等扩展功能。

Section sources

认证与权限​

所有API端点默认需要认证。系统使用JWT（JSON Web Token）进行身份验证。

  • 认证机制：请求必须在HTTP头中包含有效的JWT令牌，格式为 Authorization: Bearer <token>。
  • 权限要求：部分操作可能需要特定的ABP权限（AbpPermission），具体权限要求在各API端点中说明。

Section sources

版本控制​

所有API端点均采用URL路径进行版本控制。

  • 版本格式：api/v{version}/MyPluginName/MyEntityName
  • 示例：api/v1/MyPluginName/MyEntityName 表示v1版本的API

Section sources

分页与排序​

对于返回列表的API（如GetList），使用标准的分页和排序参数。

分页参数​

参数类型必需描述
SkipCountint否跳过的记录数，默认为0
MaxResultCountint否每页最大记录数，默认由系统配置决定

排序参数​

参数类型必需描述
Sortingstring否排序字段和方向，格式为`FieldName [asc

Section sources

API端点详情​

获取单个MyEntityName​

获取指定ID的MyEntityName信息。

  • HTTP方法：GET
  • URL路径：api/v{version}/MyPluginName/MyEntityName/{id}
  • 权限要求：无特定权限要求
  • 请求参数：
    • id (path): MyEntityName的唯一标识符 (Guid)

响应格式

{
  "id": "string",
  "code": "string",
  "name": "string",
  "sort": 0,
  "remark": "string",
  "isDisabled": true,
  "concurrencyStamp": "string"
}

状态码

状态码描述
200成功获取
401未授权
404资源未找到

Section sources

获取MyEntityName列表​

获取MyEntityName的分页列表。

  • HTTP方法：GET
  • URL路径：api/v{version}/MyPluginName/MyEntityName
  • 权限要求：无特定权限要求
  • 查询参数：
    • Filter (query): 通用过滤条件
    • Name (query): 按名称过滤
    • SkipCount (query): 跳过的记录数
    • MaxResultCount (query): 每页最大记录数
    • Sorting (query): 排序字段

响应格式

{
  "totalCount": 0,
  "items": [
    {
      "id": "string",
      "code": "string",
      "name": "string",
      "sort": 0,
      "remark": "string",
      "isDisabled": true,
      "concurrencyStamp": "string"
    }
  ]
}

状态码

状态码描述
200成功获取列表
401未授权

Section sources

创建MyEntityName​

创建一个新的MyEntityName。

  • HTTP方法：POST
  • URL路径：api/v{version}/MyPluginName/MyEntityName
  • 权限要求：需要相应创建权限
  • 请求体：MyEntityNameCreateDto 对象

请求体结构 (MyEntityNameCreateDto)

{
  "code": "string",
  "name": "string",
  "remark": "string",
  "sort": 0,
  "isDisabled": true
}

响应格式 成功时返回创建的MyEntityName对象，格式同Get响应。

状态码

状态码描述
200创建成功
400请求数据无效
401未授权
409名称已存在

Section sources

更新MyEntityName​

更新指定ID的MyEntityName。

  • HTTP方法：PUT
  • URL路径：api/v{version}/MyPluginName/MyEntityName/{id}
  • 权限要求：需要相应更新权限
  • 请求参数：
    • id (path): MyEntityName的唯一标识符 (Guid)
  • 请求体：MyEntityNameUpdateDto 对象

请求体结构 (MyEntityNameUpdateDto)

{
  "code": "string",
  "name": "string",
  "remark": "string",
  "concurrencyStamp": "string"
}

响应格式 成功时返回更新后的MyEntityName对象。

状态码

状态码描述
200更新成功
400请求数据无效
401未授权
404资源未找到
409名称已存在

Section sources

删除MyEntityName​

删除指定ID的MyEntityName。

  • HTTP方法：DELETE
  • URL路径：api/v{version}/MyPluginName/MyEntityName/{id}
  • 权限要求：需要相应删除权限
  • 请求参数：
    • id (path): MyEntityName的唯一标识符 (Guid)

响应格式 无内容（204 No Content）

状态码

状态码描述
204删除成功
401未授权
404资源未找到

Section sources

批量删除MyEntityName​

批量删除多个MyEntityName。

  • HTTP方法：DELETE
  • URL路径：api/v{version}/MyPluginName/MyEntityName
  • 权限要求：需要相应删除权限
  • 请求体：ID数组

请求体结构

["id1", "id2", "id3"]

响应格式 无内容（204 No Content）

状态码

状态码描述
204批量删除成功
401未授权

Section sources

克隆MyEntityName​

克隆一个或多个MyEntityName。

  • HTTP方法：POST
  • URL路径：api/v{version}/MyPluginName/MyEntityName/Clone
  • 权限要求：需要相应克隆权限
  • 请求体：ID数组

请求体结构

["id1", "id2", "id3"]

响应格式 返回克隆成功的新MyEntityName对象列表。

状态码

状态码描述
200克隆成功
401未授权

Section sources

调整排序​

调整指定MyEntityName的排序值。

  • HTTP方法：PUT
  • URL路径：api/v{version}/MyPluginName/MyEntityName/{id}/AdjustSort/{sort}
  • 权限要求：需要相应排序权限
  • 请求参数：
    • id (path): MyEntityName的唯一标识符 (Guid)
    • sort (path): 新的排序值 (int)

响应格式 无内容（204 No Content）

状态码

状态码描述
204排序调整成功
401未授权

Section sources

导入MyEntityName​

从Excel文件导入MyEntityName数据。

  • HTTP方法：POST
  • URL路径：api/v{version}/MyPluginName/MyEntityName/Import
  • 权限要求：需要相应导入权限
  • 请求类型：multipart/form-data
  • 请求参数：
    • file (form-data): Excel文件

响应格式

{
  "success": true
}

状态码

状态码描述
200导入成功
400文件格式错误或数据校验失败
401未授权

Section sources

导出MyEntityName​

导出MyEntityName数据到Excel文件。

  • HTTP方法：GET
  • URL路径：api/v{version}/MyPluginName/MyEntityName/Export
  • 权限要求：需要相应导出权限
  • 查询参数：同GetList的查询参数

响应格式 返回Excel文件流，Content-Type为application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

状态码

状态码描述
200导出成功，返回文件流
401未授权

Section sources

数据模型​

MyEntityNameDto​

MyEntityName的数据传输对象。

属性类型描述
IdGuid唯一标识符
Codestring编号
Namestring名称
Sortint排序
Remarkstring备注
IsDisabledbool?是否禁用
ConcurrencyStampstring并发戳

Section sources

MyEntityNameCreateDto​

创建MyEntityName的请求对象。

属性类型描述
Codestring编号
Namestring名称
Remarkstring备注
Sortint?排序
IsDisabledbool?是否禁用

Section sources

MyEntityNameUpdateDto​

更新MyEntityName的请求对象。

属性类型描述
Codestring编号
Namestring名称
Remarkstring备注
ConcurrencyStampstring并发戳

Section sources

GetMyEntityNamesInput​

获取MyEntityName列表的查询参数。

属性类型描述
Filterstring通用过滤条件
Namestring按名称过滤
SkipCountint跳过的记录数
MaxResultCountint每页最大记录数
Sortingstring排序字段

Section sources

MyEntityNamesImportModel​

导入MyEntityName的模型。

属性类型描述
MyEntityNamesList<MyEntityNameImportModel>要导入的MyEntityName列表

Section sources

MyEntityNamesExportModel​

导出MyEntityName的模型。

属性类型描述
WorkSectionExportModelclass导出模型，包含Name、Code、Remark字段

Section sources

错误处理​

API使用标准的HTTP状态码表示请求结果。

常见错误码​

状态码错误类型描述
400Bad Request请求数据格式错误或校验失败
401Unauthorized未提供或提供了无效的认证令牌
403Forbidden用户没有执行此操作的权限
404Not Found请求的资源不存在
409Conflict资源冲突，如名称已存在
500Internal Server Error服务器内部错误

错误响应格式​

{
  "error": {
    "code": "string",
    "message": "string",
    "details": "string",
    "validationErrors": [
      {
        "message": "string",
        "members": ["string"]
      }
    ]
  }
}

Section sources

使用示例​

创建MyEntityName的curl示例​

curl -X POST "https://your-api-domain/api/v1/MyPluginName/MyEntityName" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "MY001",
    "name": "示例名称",
    "remark": "这是一个示例"
  }'

获取MyEntityName列表的curl示例​

curl -X GET "https://your-api-domain/api/v1/MyPluginName/MyEntityName?Name=示例&Sorting=Name%20desc&MaxResultCount=10" \
  -H "Authorization: Bearer your-jwt-token"

导入MyEntityName的curl示例​

curl -X POST "https://your-api-domain/api/v1/MyPluginName/MyEntityName/Import" \
  -H "Authorization: Bearer your-jwt-token" \
  -F "file=@myentitynames.xlsx"

Section sources