microsoft / microsoft/OpenAPI.NET
Consider returning reference type from `AddComponent` API
Nobody has claimed this yet.
- Dominant language
- C#
- Stars
- 1.6k
- Forks
- 286
- Avg merge
- 6h 38m
- Merged PRs (30d)
- 35
Description
The AddComponent API currently returns a boolean that indicates if the addition of the component to the document registry succeeded.
It would be nice if the API returned a reference to the item that was just constructed. In an M.A.OpenAPI transformer, I currently need to write:
options.AddOperationTransformer((operation, context, cancellationToken) =>
{
var schemaService = context.ApplicationServices.GetRequiredKeyedService<IOpenApiSchemaService>(context.DocumentName);
if (context.Description.RelativePath == "error")
{
var errorSchema = schemaService.GetOrCreateSchema(typeof(ProblemDetails));
context.Document.AddComponent("Error", errorSchema);
operation.Responses["500"] = new OpenApiResponse
{
Description = "Error",
Content =
{
["application/problem+json"] = new OpenApiMediaType
{
Schema = new OpenApiSchemaReference("Error", context.Document),
},
},
};
}
return Task.CompletedTask;
});
but would like to write:
options.AddOperationTransformer((operation, context, cancellationToken) =>
{
var schemaService = context.ApplicationServices.GetRequiredKeyedService<IOpenApiSchemaService>(context.DocumentName);
if (context.Description.RelativePath == "error")
{
var errorSchema = schemaService.GetOrCreateSchema(typeof(ProblemDetails));
var insertedSchema = context.Document.AddComponent("Error", errorSchema);
operation.Responses["500"] = new OpenApiResponse
{
Description = "Error",
Content =
{
["application/problem+json"] = new OpenApiMediaType
{
Schema = insertedSchema,
},
},
};
}
return Task.CompletedTask;
});
cc: @baywet I couldn't see if an API that did this existed already and figured I'd add the proposal.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the AddComponent API implementation and any existing coverage for document component registration. Compare its current boolean result with the AddOperationTransformer example, then verify that the returned reference represents the inserted schema while existing registration behavior remains intact.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100