接口文档

DZ-SHOP自研并内置了完善的、查看、搜索、测试于一体的后台与客户端API文档。

访问接口文档

小贴士

接口文档必须在开发环境下才能访问。因此需要访问接口文档，在安装系统时就应该选择“开发环境”。

• 访问后台API文档

http://你的域名/backendApi/api-doc

• 访问客户端API文档

http://你的域名/frontendApi/api-doc

• 访问SAAS中心API文档（SAAS版本）

http://你的域名/centerApi/api-doc

接口文档图例

编写接口文档

如果你需要二次开发新增接口，接口文档的配置是非常简单且高效的，只要给接口配置好了属性标记，接口将自动动态生成。在配置新增的接口文档之前，你需要了解Attributes。

定义一个Module

#[ApiModule('我的接口')]
class Module extends \yii\base\Module
{
    
}

定义一个功能类并分组

#[ApiController(brief: '我的功能', sort: 1, group: ApiGroup::BASE)]
class YourNameController extends Controller
{

}

定义一个功能接口

#[ApiController(brief: '我的功能', sort: 1, group: ApiGroup::BASE)]
class YourNameController extends Controller
{
    #[ApiMethod(
        brief: '测试',
        sort: 1,
        verbs: [VerbsEnum::GET],
        isAuth: false,
        params: [
            new ApiParam(name: 'param1', verb: ParamVerbsEnum::GET, brief: '参数1', required: false)
        ],
        returns: [
            new ApiReturn(type: DataTypeEnum::String, brief: '返回字符串'),
        ],
    )]
    public function actionIndex(): String
    {
        return 'Hello World!';
    }
}

使用自动化token认证

特别注意

自动化token认证不要在生产环境中使用，否则您的服务器将面临不可挽回的安全灾难！

自动化token用于可以在后台测试时，自动填充token字段，更加方便进行测试。

后台APIDOC使用自动化token认证：

在 config/backendApi/main-local.php 中找到 “new ApiHeader("x-api-key","token字符串，如果接口需要登录则必须有值",false)” 替换为 “new ApiHeader("x-api-key","token字符串，如果接口需要登录则必须有值",false,'','\backendApi\apidoc\XApiKeyDefaultValue',['id'=>1])” 即可。其中 'id'=>1 可以将值设置为你想自动生成token的后台用户ID。

客户端APIDOC使用自动化token认证：

在 config/frontendApi/main-local.php 中找到 “new ApiHeader("x-api-key","token字符串，如果接口需要登录则必须有值",false)” 替换为 “new ApiHeader("x-api-key","token字符串，如果接口需要登录则必须有值",false,'','\frontendApi\apidoc\XApiKeyDefaultValue',['id'=>1])” 即可。其中 'id'=>1 可以将值设置为你想自动生成token的客户端用户ID。