Model the local API Explorer fixtures without a key prefix hack

Aperta
  • Qualcosa non va?
#4,721 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Refactoring
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
csharp
Ambito
tooling

Direzione di ricerca

Read docs/_docset.yml, src/Elastic.ApiExplorer/Infrastructure/IsolatedApiAliases.cs, OpenApiGenerator.ApiConfigsToRender, and AssemblerOpenApiBuildStep.DiscoverApiOwners to trace how fixture keys are declared and handled. Compare explicit fixture metadata with moving fixtures out of the product namespace, then choose a design that keeps the docset key and URL key identical. Done means assembler builds skip fixtures and isolated builds serve them under that same key.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

enhancement needs triage tech-debt

The docs-builder- prefix on API keys in docs/_docset.yml exists only so this repo can preview API pages locally, and it should be modeled explicitly.

What is getting in your way

docs/_docset.yml declares its API fixtures as docs-builder-elasticsearch, docs-builder-kibana and so on. These are copies of product specs for isolated preview. The assembler also loads this checkout, and two docsets that declare the same API key produce a Duplicate API key error in DiscoverApiOwners. The prefix avoids that error, and several places then special-case it:

  • IsolatedApiAliases.IsFixtureKey and IsolatedApiAliases.UrlKey in src/Elastic.ApiExplorer/Infrastructure/IsolatedApiAliases.cs recognize and strip the prefix.
  • OpenApiGenerator.ApiConfigsToRender skips the keys in the assembler and shortens them in isolated builds.
  • AssemblerOpenApiBuildStep.DiscoverApiOwners skips them.

The declared key and the URL key differ in this one repo. An api: elasticsearch toc entry from Mount API pages in the navigation of isolated builds matches the short key, not the declared one, which is easy to get wrong.

What would you like instead

A fixture is a declared concept and not a naming convention. For example, an api: entry could carry a flag such as fixture: true, or the fixtures could move out of the product namespace. Then the assembler can skip them without reading a prefix, and isolated builds can serve them under their normal key.

Whatever shape wins, the key in docset.yml and the key in the URL should be the same string.

Anything else

The history does not state why the prefix exists. The reason above comes from reading the code that uses it. The change was introduced in Restyle API Explorer pages, sidebar, and top bar.

This is accepted as it is for now. RFC: Floating sections in the navigation tree works with the prefix as it is.

Lingua principale
C#
Stelle
25
Fork
44
Merge medio
17h 21m
PR unite (30g)
343

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di elastic/docs-builder

Tutte le issue di elastic/docs-builder

Issue simili

Altre issue su C#

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.