Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

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

Aberta
  • Algo errado?
#257 1 comentário 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
48/100
Tipo de issue
Funcionalidade
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
azure, typescript
Domínio
api, cli, documentation

Direção de pesquisa

Comece pelo ponto de entrada apiops extract e leia docs/commands/extract.md e README.md para entender o comportamento existente de --format. Rastreie como os artefatos de especificação extraídos são selecionados e como os formatos de exportação do APIM são representados. O trabalho estará concluído quando os tipos de API compatíveis aceitarem um formato de especificação explícito, o comportamento automático for preservado quando ele for omitido, os casos não compatíveis forem validados e a distinção e as orientações de migração forem documentadas.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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

Linguagem predominante
TypeScript
Estrelas
32
Forks
12
Merge médio
2d 14h
PRs com merge (30d)
21

Preparar o ambiente

Abrir no Codespaces

Inicia o contêiner de desenvolvimento do projeto no navegador, com a sua própria conta do GitHub.

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de Azure/apiops-cli

Todas as issues de Azure/apiops-cli

Issues semelhantes

Mais issues de TypeScript

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.