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

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