Feature Request: Power Platform OpenAPI Spec Generator Plugin

[rwilson504]

Summary

Add a new plugin to dev-proxy that generates OpenAPI specifications tailored for Microsoft Power Platform connectors. This plugin should build on the existing OpenApiSpecGeneratorPlugin, but add Power Platform–specific metadata, conventions, and configuration options.

---

Motivation

• Power Platform connectors require OpenAPI 2.0 specs with specific metadata (contact, x-ms-connector-metadata, etc.).
• The current OpenApiSpecGeneratorPlugin does not enforce all Power Platform requirements or provide Power Platform-specific enhancements (e.g., LLM-powered summaries, stricter response schema rules).
• Users need a simple way to generate Power Platform–ready specs directly from dev-proxy.

---

Proposed Solution

1. New Plugin: PowerPlatformSpecGeneratorPlugin

• Inherits or reuses logic from OpenApiSpecGeneratorPlugin (via post-processing or code sharing).
• Adds/overrides:
  • Forces OpenAPI 2.0 output (specVersion: v2_0).
  • Allows YAML or JSON output (specFormat).
  • Adds contact and connectorMetadata sections to the OpenAPI info and extensions.
  • Only the lowest 2xx response gets a schema and uses "default" as the description; all others use response.StatusDescription and have no schema.
  • Uses LLM to generate property titles, summaries, and descriptions.
  • Optionally skips OPTIONS requests.
  • Optionally includes/excludes response headers.

2. Config Schema Additions

• specFormat: "Json" or "Yaml" (default: "Json")
• includeOptionsRequests: boolean (default: false)
• includeResponseHeaders: boolean (default: false)
• contact: { name, url, email } (optional)
• connectorMetadata: { website, privacyPolicy, categories } (optional, each field optional)

3. Example Config

{
  "specFormat": "Yaml",
  "includeOptionsRequests": false,
  "includeResponseHeaders": true,
  "contact": {
    "name": "Contoso API Team",
    "url": "https://contoso.com",
    "email": "api@contoso.com"
  },
  "connectorMetadata": {
    "website": "https://contoso.com",
    "privacyPolicy": "https://contoso.com/privacy",
    "categories": "Data,AI"
  }
}

4. Behavior

• If both plugins are used, PowerPlatformSpecGeneratorPlugin should post-process the output of OpenApiSpecGeneratorPlugin, enforcing Power Platform requirements.
• If only PowerPlatformSpecGeneratorPlugin is used, it should generate the spec directly with all Power Platform conventions.

---

Tasks

• Add PowerPlatformSpecGeneratorPlugin to the project.
• Add/extend config schema (powerplatformspecgeneratorplugin.schema.json) with new options.
• Implement post-processing logic to add Power Platform–specific metadata and enforce response/schema rules.
• Ensure LLM integration for property titles, summaries, and descriptions.
• Update documentation with usage instructions and config examples.
• Add tests to verify Power Platform–compliant output.

---

References

• Power Platform Custom Connector OpenAPI requirements
• Create a custom connector with an OpenAPI extension
• Prepare connector files for certification
• Power Platform schema for apiDefinition.swagger.schema.json

[waldekmastykarz]

Great suggestion @rwilson504!

[waldekmastykarz]

@rwilson504 could you please double check the OpenAPI requirements link? It's giving me a 404

[waldekmastykarz]

Also, let's include an example OpenAPI spec with the necessary properties. It will help us understand what hooks we'd need in the generation process to accommodate them.

[rwilson504]

Double checked the links and added a link to the schema for connectors from the MSFT repo.