Hacktoberfest 2026: die Issues, die Maintainer für den Oktober markiert haben – offen und einsteigerfreundlich. Hacktoberfest-Issues durchsuchen

Add specification format selection to `apiops extract` for feature parity with `Azure/apiops`

Offen
  • Stimmt etwas nicht?
#257 1 Kommentar 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Anfängerfreundlichkeit
48/100
Issue-Typ
Feature
Klarheit
Größtenteils klar
Aktivitätsstatus
Aktiv
Tech-Stack
azure, typescript
Bereich
api, cli, documentation

Rechercherichtung

Beginne mit dem Einstiegspunkt apiops extract und lies docs/commands/extract.md sowie README.md, um das bestehende Verhalten von --format zu verstehen. Verfolge, wie extrahierte Spezifikationsartefakte ausgewählt werden und wie APIM-Exportformate dargestellt werden. Als abgeschlossen gilt, wenn unterstützte API-Typen ein explizites Spezifikationsformat akzeptieren, das automatische Verhalten bei Weglassen beibehalten wird, nicht unterstützte Fälle validiert werden und die Unterscheidung sowie Migrationshinweise dokumentiert sind.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

type:feature
Problem or use case

apiops extract currently lets users control the CLI stdout format via --format text|json, but it does not expose a user-facing option to control the exported API specification artifact format itself.

The current docs make this distinction visible:

  • docs/commands/extract.md documents --format <type> only as a global flag for command output (text or json).
  • The extract output section describes the artifact tree in general, but there is no documented flag to choose whether an extracted API specification is written as OpenAPI YAML vs JSON when APIM supports both.

This is a migration and usability gap for teams coming from the previous Azure/apiops repository, where specification output format selection was available. In apiops-cli, specification format selection is currently automatic/internal, which makes artifact output less predictable for users who:

  • want consistent JSON specs across repositories and environments,
  • need JSON for downstream tooling, validation, or transformations,
  • want explicit control instead of source-dialect-based auto-selection,
  • are migrating existing workflows from Azure/apiops and expect the same capability.

The current behavior can also be confusing because --format json sounds like it might affect extracted spec files, but according to the current command documentation it only affects machine-readable command output written to stdout.

Proposed solution

Add a user-facing option to explicitly select the exported API specification artifact format during extraction, while preserving the current automatic behavior as the default.

Suggested behavior:

  • Add a dedicated extract flag for specification artifact format selection, for example:
    • apiops extract --specification-format json
    • apiops extract --specification-format yaml
  • Scope this flag to API specification artifacts only, not general command output.
  • Keep --format text|json unchanged so it continues to mean stdout/log output format only.
  • When the new specification-format flag is omitted, preserve today's automatic behavior.
  • Validate unsupported combinations clearly. For example:
    • API types with no specification export should ignore or reject the option with a clear message.
    • Formats unsupported by the underlying APIM export path should fail fast with actionable guidance.
  • Document the mapping between the new CLI flag and the APIM export formats used internally.

Recommended documentation updates:

  • Update docs/commands/extract.md to distinguish:
    • --format = stdout format
    • --specification-format = extracted API spec artifact format
  • Add examples showing the new flag with apiops extract
  • Update migration guidance for users moving from Azure/apiops
  • Update artifact format/reference docs so the expected file extension/content is explicit

Suggested acceptance criteria:

  • Users can explicitly choose the extracted specification artifact format for supported API types.
  • For REST APIs where APIM supports multiple export forms, users can choose JSON vs YAML.
  • The selected format controls the written spec artifact consistently.
  • Existing extract behavior remains unchanged when the new flag is omitted.
  • The docs clearly distinguish stdout formatting from specification artifact formatting.
  • Migration documentation calls out this feature as parity with Azure/apiops.

Relevant current documentation context:

  • docs/commands/extract.md shows:
    • --format <type> with values text or json
    • “Machine-readable JSON output” as stdout behavior
  • README.md also documents --format <type> globally as text or json
  • Integration docs already show that the project cares about spec dialect/format fidelity across API types, including:
    • REST OpenAPI 3.0 YAML
    • REST Swagger 2.0 JSON
    • SOAP WSDL
    • GraphQL SDL

That existing format awareness makes explicit user selection feel like a natural extension of the current extract model.

Affected command

apiops extract

Vorherrschende Sprache
TypeScript
Sterne
32
Forks
12
Ø Merge
2 T. 14 Std.
Gemergte PRs (30 T.)
21

Entwicklungsumgebung

In Codespaces öffnen

Startet den Dev-Container des Projekts im Browser, mit Ihrem eigenen GitHub-Konto.

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus Azure/apiops-cli

Alle Issues in Azure/apiops-cli

Ähnliche Issues

Weitere Issues zu TypeScript

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.