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

从 apiops extract 入口开始，阅读 docs/commands/extract.md 和 README.md，了解现有的 --format 行为。跟踪如何选择提取的规范工件，以及如何表示 APIM 导出格式。当受支持的 API 类型接受显式的规范格式、在省略该格式时保留自动行为、验证不受支持的情况，并记录其中的区别和迁移指南时，即视为完成。

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