Azure / Azure/azure-functions-openapi-extension

Does not generate valid OpenApi 3.0.1 spec; mutually exclusive `example` and `examples` elements are both generated.

Open
#662 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C#
Stars
388
Forks
202
PR merge metrics
No merged PRs in 30d

Description

Given the function

```csharp
using System.Net;
using System.Net.Mime;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Abstractions;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Resolvers;
using Microsoft.Extensions.Logging;
using Microsoft.OpenApi.Models;
using Newtonsoft.Json.Serialization;

namespace PocApiDescFunction;

public class HttpHelloMe
{
private readonly ILogger _logger;

public HttpHelloMe(ILogger logger)
{
_logger = logger;
}

[Function(nameof(HttpHelloMe))]
[OpenApiOperation(operationId: "Greeting", tags: ["GM"])]
[OpenApiParameter(name: "name", In = ParameterLocation.Path, Required = true, Type = typeof(string),
Description = "The name of the person.")]
[OpenApiResponseWithBody(
statusCode: HttpStatusCode.OK,
contentType: MediaTypeNames.Application.Json,
bodyType: typeof(Hello),
Description = "It is always a great day to have a great day!",
Example = typeof(HelloOpenApiExample))]
[OpenApiResponseWithoutBody(
statusCode: HttpStatusCode.NotFound,
Description = "Non alpha name is not allowed.")]
public IActionResult Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get",
Route = "hello/{name:alpha}")]
HttpRequest req, string name)
{
_logger.LogInformation("Going to say GM to {name}.", name);
return new OkObjectResult(new Hello($"GM, {name}!"));
}
}

public class HelloOpenApiExample : OpenApiExample
{
public override IOpenApiExample Build(NamingStrategy? namingStrategy = null)
{
Examples.Add(OpenApiExampleResolver.Resolve("{name=John}", "John appears!", new Hello("GM, John!"), namingStrategy));
Examples.Add(OpenApiExampleResolver.Resolve("{name=Sandy}", "Sandy appears!", new Hello("GM, Sandy!"), namingStrategy));
return this;
}
}

public record Hello(string Message);
```

outputs
```yaml
openapi: 3.0.1
info:
title: OpenAPI Document on Azure Functions
description: This is the OpenAPI Document on Azure Functions
version: 1.0.0
servers:
- url: https://poc-apim-function.azurewebsites.net/api
paths:
'/hello/{name}':
get:
tags:
- GM
operationId: Greeting
parameters:
- name: name
in: path
description: The name of the person.
required: true
schema:
type: string
responses:
'200':
description: It is always a great day to have a great day!
content:
application/json:
schema:
$ref: '#/components/schemas/hello'
example: '{"message":"GM, John!"}'
examples:
'{name=John}':
summary: John appears!
value: '{"message":"GM, John!"}'
'{name=Sandy}':
summary: Sandy appears!
value: '{"message":"GM, Sandy!"}'
'404':
description: Non alpha name is not allowed.
components:
schemas:
hello:
type: object
properties:
message:
type: string
```

Contributor guide

Open the contributing guide

Research direction

Start with the reproduced HttpHelloMe function, especially OpenApiResponseWithBody and HelloOpenApiExample.Build, then inspect how its response is rendered into the shown YAML. Done means the generated OpenAPI 3.0.1 response contains either example or examples as appropriate, not both, and validates against the specification.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, openapi
Domain
api
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.