Question

我在一个ApiResource上有三个集合操作，它们具有不同的normalization_context和filters。

/equipments检索所有设备（在当前用户上过滤）
/equipments/A检索符合规则A的所有设备
/equipments/B检索符合规则B的所有设备

在嵌套属性（相关实体的ID）上设置了一些过滤器。我想为API使用者提供可用于某些过滤器的值。假设我有一个由所有端点共享的公司过滤器。

对于/equipments，允许的值为1,2,3
对于/equipments/A，允许的值为4,5,6
对于/equipments/B，允许的值为1,3,5

我看到的解决方案是为每个将返回具有允许值的过滤器的操作添加.../filters端点。

GET /equipments/filters

[
    {
        'name': 'company',
        'type': integer,
        'choices': [
            'Company 1': 1,
            'Company 2': 2,
            'Company 3': 3,
        ]
    },
    {
        'name': 'operator',
        'type': autocomplete,
        'url': /equipments/filters/operator?q={q}
    }
]

加分问题：如果这是一个很好的解决方案，我在哪里以及如何在JSON-LD / Hydra文档中添加这些操作？

Answer 1

大多数API文档格式（包括Swagger和JSON-LD（由API平台支持））允许为过滤器指定有效值，而无需执行自定义操作。

使用Swagger，您可以使用enum对象的parameter属性来定义有效值：https://swagger.io/docs/specification/2-0/enums/

paths:
  /equipments/B:
    get:
      parameters:
        - in: query
          name: company
          description: A company filter
          type: integer
          enum: [1, 3, 5]

如果您更喜欢使用Hydra，可以使用模板化链接来实现您想要的效果：

{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
  "@type": "IriTemplate",
  "template": "/equipments/B{?company}",
  "mappings": [
    {
      "@type": "IriTemplateMapping",
      "variable": "company",
      "property": "http://example.com/myCompanyType"
    }
  ]
}

然后，您需要通过添加返回适用值的端点动态返回值，或者如果列表是静态的，则直接在词汇表中的词汇表中返回值（例如http://schema.org/ActionStatusType）。

要向API平台添加此类信息，您需要修饰生成文档的内置服务。 Swagger示例：https://github.com/api-platform/docs/blob/master/core/swagger.md#override-swagger-documentation

管理集合中过滤器的最佳方法

1 个答案: