edit-endpoint

用途

该技能面向 datagouv/apistration 项目中 API 端点文档的编辑工作。它用于修改一个 API 端点的文档，包括两类内容：业务说明卡（fiche metier，如范围、FAQ、关键词、描述）以及 Swagger 文档（OpenAPI 结构、属性、标签）。

文件位置与查找

所有端点文件都位于 commons/endpoints/ 目录下，其中包含：

commons/endpoints/
  api_entreprise/*.yml      # endpoints API Entreprise
  api_particulier/*.yml     # endpoints API Particulier
  _swagger_shared/          # swagger 共享（端点之间的 YAML 锚点）

按 uid 查找端点：

grep -r "uid: 'provider/resource'" commons/endpoints/

端点文件格式

端点文件由 fiche: 与 swagger: 两部分组成，格式示例如下（保留原始结构）：

fiche:
  - uid: 'provider/resource'
    path: '/v3/provider/resource/{param}'
    controller: 'api_entreprise/v3_and_more/provider/resource'  # cf. section dediee
    position: 501                    # ordre dans le catalogue
    opening: protected               # protected ou public
    provider_uids: ['provider']
    call_id: "SIRET"
    keywords: [mot, cle]
    perimeter:
      entity_type_description: |+    # qui est concerne
      geographical_scope_description: |+
      updating_rules_description: |+
      know_more_description: |+
      entities: [entreprises, associations]
    data:
      description: |+                # description des donnees renvoyees
    parameters:
      - Description du parametre
    format:
      - Donnee structuree JSON
    faq:
      - q: "Question ?"
        a: |+ Reponse
    historique: |+                    # changelog entre versions
    swagger:
      provider.resource_name:        # cle dottee = SwaggerData.get path
        title: "Titre swagger"
        description: "Description technique"
        tags: ["Categorie"]
        attributes:                  # ou document_url_properties pour PDF
          champ:
            type: "string"
            title: "Titre"
            example: "valeur"

controller 字段

controller 必须指向 siade 端真实的 Rails controller（不带 #action）。它用于 fournisseur dashboard，将说明卡关联到 access_logs.controller。查找方式：

cd siade && bundle exec rails routes | grep '<provider>'

示例：

api_entreprise/v3_and_more/insee/etablissements        (entreprise v3+)
api_particulier/v3_and_more/cnav/quotient_familial     (particulier v3+)
api_particulier/v2/cnav/quotient_familial              (particulier v2 legacy)

修改业务说明卡（Fiche metier）

修改 fiche: 下的（除 swagger: 之外的）字段，验证命令：

cd site && bundle exec rspec spec/stores/

修改 Swagger

端点内嵌 Swagger

修改 fiche[].swagger:。点号键（provider.resource_name）对应 rswag specs 中的 SwaggerData.get('provider.resource_name.property')。

位于 _swagger_shared/ 的 Swagger

多端点 provider 将其 swagger 保存在 _swagger_shared/<provider>.yml：insee、cnav、dgfip、inpi_rne、mi、infogreffe、cnous、mesri、men、france_travail、gip_mds。

共享定义：_swagger_shared/00_commons.yml（SIREN/SIRET 参数）、_swagger_shared/civility.yml（identite pivot）。

验证 Swagger：

cd siade && bundle exec rspec spec/requests/api_entreprise/v3_and_more/<provider>/<resource>/
bin/generate_swagger.sh

新增一个端点

复制模板：commons/endpoints/template.entreprise.yml.example（或 particulier）
在 commons/endpoints/api_entreprise/ 或 api_particulier/ 中创建文件
填写 fiche + swagger
在 siade/spec/requests/ 创建 rswag spec
运行 cd siade && bin/generate_swagger.sh

适用场景

需要更新 API Entreprise 或 API Particulier 端点文档时
需要补充或修改端点的业务范围、FAQ、关键词、描述时
需要调整端点 Swagger（OpenAPI）结构、属性或标签时
需要新增端点文档并生成 Swagger 时

限制

关于收费、价格、平台支持范围、实际效果等具体信息，资料暂未提供。该技能的操作对象限定为 apistration 仓库中的端点文件，实际执行需具备对 siade、site 等关联项目与 Rails 环境的访问能力。