[Repo Assist] improve: enrich XML documentation for generated API methods#349
Conversation
…scriptions and remarks - Build structured XML doc (<summary>, <remarks>, <param>) instead of plain text - Add <param name="..."> entries for OpenAPI parameters that have descriptions - Add <remarks> for operation.Description when it differs from Summary - Apply same improvement to both v2 (SwaggerClientProvider) and v3 (OpenApiClientProvider) - XML-escape description text to prevent malformed doc comments - Resolves the TODO comment that has been in the code since the initial implementation 241 unit tests pass; format check passes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
/repo-assist refactor code and reuse xml generation code between v2 and v3 |
|
✗ Repo Assist encountered failed at {run-ended}. |
|
@copilot refactor code and reuse xml generation code between v2 and v3 |
Agent-Logs-Url: https://github.com/fsprojects/SwaggerProvider/sessions/1ebc143c-89b5-4035-8920-2271a97cde2b Co-authored-by: sergey-tihon <1197905+sergey-tihon@users.noreply.github.com>
Done in f7feb4c. Extracted a shared Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
There was a problem hiding this comment.
Pull request overview
This PR improves the XML documentation emitted for generated API client methods (both Swagger v2 and OpenAPI v3) by converting plain summary text into structured XML docs and including operation descriptions and parameter descriptions.
Changes:
- Add
XmlDoc.buildXmlDochelper to construct<summary>,<remarks>, and<param>tags with basic XML escaping. - Update v3
OperationCompilerto emit structured XML docs, including request-body and parameter descriptions. - Update v2
OperationCompilerto emit structured XML docs, including parameter descriptions.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| src/SwaggerProvider.DesignTime/v3/OperationCompiler.fs | Builds XML doc fragments for generated v3 methods, including per-parameter docs and request-body docs. |
| src/SwaggerProvider.DesignTime/v2/OperationCompiler.fs | Builds XML doc fragments for generated v2 methods, including per-parameter docs. |
| src/SwaggerProvider.DesignTime/Utils.fs | Introduces a shared XmlDoc helper to build and escape structured XML doc fragments. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
🤖 This is a Repo Assist automated PR.
Implements the long-standing
TODO: Use description of parameters in docscomment in bothv2/OperationCompiler.fsandv3/OperationCompiler.fs.Problem
Generated API client methods had minimal XML documentation — only the OpenAPI
summaryfield was surfaced as a plain text doc comment. Thedescriptionfield and individual parameter descriptions were silently discarded.Changes
v3/OperationCompiler.fs<summary>,<remarks>, and<param>tags<remarks>fromoperation.Descriptionwhen it differs fromSummary<param name="...">...</param>for eachopenApiParametersentry that has a description<param name="...">...</param>for the request body whenRequestBody.Descriptionis set&,<,>) to prevent malformed doc commentsv2/OperationCompiler.fsSwaggerClientProvider-generated methodsop.Parameters[].Description<remarks>fromop.Descriptionwhen it differs fromop.SummaryBefore / After example
No changes to generated runtime behaviour — only IntelliSense / XML doc output is affected.
Test Status
✅ Unit tests: 241 passed, 0 failed
⚠️ Integration tests: Test server cannot start in this CI environment (pre-existing infrastructure constraint — same limitation affects all Repo Assist PRs targeting integration tests).
✅ Format check (
dotnet fantomas --check): passed