[waldekmastykarz]

Closes #2066

What

devproxy api show --output json now includes, per endpoint:

• parameters – query parameters (name, in: "query", description, required, JSON schema)
• requestBody – required + content map with a JSON schema (and an example)
• responses – keyed by status code, each with description and an optional content map with a schema

Shapes follow OpenAPI 3.1 conventions so agents and tools recognize them. For example, GET /proxy/rootCertificate now documents the required format=crt query parameter and 400, and POST /proxy/stopProxy documents 202.

Text output is unchanged.

Overlap with #2092 (#2065)

#2092 adds short human-readable query and body hint strings to each endpoint (text and JSON). This PR is complementary and uses different keys so both coexist in the JSON output:

Key	From	Purpose
query, body	#2092	One-line hints, e.g. format=crt (required)
parameters, requestBody, responses	this PR	Machine-readable, OpenAPI-shaped schemas

Both PRs touch the JSON projection in ApiCommand.PrintApiInfo; whichever merges second needs a trivial merge there (keep all five keys). Schemas live in a separate ApiEndpointSchemas file to keep the overlap that small.

Why this option (and not serving /openapi.json)

The issue offered two options. I chose extending api show:

• Works without a running proxy. api show is what agents read first, typically before Dev Proxy starts. An OpenAPI endpoint is only reachable after startup and with a token.
• No new dependencies. Serving OpenAPI needs Microsoft.AspNetCore.OpenApi (Swashbuckle was removed in Update deps. Closes #1637 #1647), and the generated document would need customization anyway (status codes set via Response.StatusCode, content negotiation on /proxy/logs).
• One discovery path. The existing JSON already has baseUrl and authentication; adding schemas keeps everything in one place.

Other changes

• devproxy --help advertised an OpenAPI spec at <api>/swagger, which no longer exists (404). It now shows the API URL and points to devproxy api show --output json.
• Updated the CI/CD skill reference to mention the JSON output.

Keeping schemas accurate

Schemas live in ApiEndpointSchemas (separate from ApiCommand to stay out of the way of #2065). Tests use reflection on ProxyController to fail when:

• a controller endpoint has no schema
• [FromQuery] parameters or their [Required]-ness differ from parameters
• [FromBody] presence differs from requestBody
• JwtOptions, ProxyInfo or the logs entry DTO gain or lose properties

Verification

• dotnet test DevProxy.Tests – 46 passed
• Started a detached proxy and called every endpoint; status codes and content types match the documented ones (including application/problem+json for 400s, and the PascalCase property names /proxy/logs actually returns for JSON).

[Copilot]

🟡 Changes recommended

The discovery schemas omit the logs endpoint’s 400 query-validation response and allow status payloads containing non-null configFile values that the controller rejects.

2 open issues

• Disallow unsupported configFile in the request schema · New
• Document 400 responses for query-validation failures · New

What changed in this PR

Extends Dev Proxy’s offline API discovery with request and response schemas, helping agents and tools construct API calls without a running proxy. Text output remains unchanged.

Changes:

• Adds query parameters, request bodies, and response schemas to api show --output json.
• Adds reflection-based tests to detect drift between schemas and controller contracts.
• Replaces the obsolete Swagger help link and documents JSON discovery.

File	Description
skills/​dev-proxy/​references/​ci-cd-integration.md	Documents JSON output for API discovery.
DevProxy/​Commands/​DevProxyCommand.cs	Replaces the Swagger link with API discovery guidance.
DevProxy/​Commands/​ApiEndpointSchemas.cs	Defines endpoint request and response schemas.
DevProxy/​Commands/​ApiCommand.cs	Includes schemas in JSON endpoint output.
DevProxy.Tests/​ApiEndpointSchemasTests.cs	Checks schema coverage and controller alignment.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The lifetime schema permits negative validFor values, allowing schema-valid requests that fail during token creation because expiration precedes the not-before time.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Require positive values for validFor in the lifetime schema

DevProxy/​Commands/​ApiEndpointSchemas.cs:169

The lifetime schema accepts negative values, so a client can generate a schema-valid request such as {"validFor": -1} that fails during token creation: JwtCreatorOptions.Create puts ExpiresOn before NotBefore, and JwtIssuer passes those dates to CreateJwtSecurityToken, which rejects them. Please constrain validFor to a positive number so the discovery schema does not advertise these failing requests as valid.

2 resolved since last review

• Document 400 responses for query-validation failures
• Disallow unsupported configFile in the request schema

_{Review effort: Balanced}

[waldekmastykarz]

Addressed the previously missed validFor issue: the schema now uses exclusiveMinimum: 0 (dfc66a2).

[Copilot]

🟢 Approval recommended

No active review issues remain that require changes.

No open issues 🎉

_{Review effort: Balanced}