Azure / Azure/azure-functions-openapi-extension

Example for an OpenApiParameter leads to a 'structural error' validation error in the generated swagger.json

Open
#517 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

**Describe the issue**
When you specify an example for a query parameter the generated swagger.json file has a validation error due to both 'example' and 'examples' fields being present. These fields are mutually exclusive per the [spec](https://swagger.io/specification/#parameter-object).

**To Reproduce**
- Create a get endpoint with a query parameter with an example. e.g.
```
[FunctionName(nameof(PetHttpTrigger.GetPetById))]
[OpenApiOperation(operationId: "getPetById", tags: new[] { "pet" }, Summary = "Find pet by ID", Description = "Returns a single pet.", Visibility = OpenApiVisibilityType.Important)]
[OpenApiSecurity("api_key", SecuritySchemeType.ApiKey, Name = "api_key", In = OpenApiSecurityLocationType.Header)]
[OpenApiParameter(name: "petId", In = ParameterLocation.Path, Required = true, Type = typeof(long), Example = typeof(PetIdExample), Summary = "ID of pet to return", Description = "ID of pet to return", Visibility = OpenApiVisibilityType.Important)]
[OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json", bodyType: typeof(Pet), Summary = "successful operation", Description = "successful operation")]
[OpenApiResponseWithoutBody(statusCode: HttpStatusCode.BadRequest, Summary = "Invalid ID supplied", Description = "Invalid ID supplied")]
[OpenApiResponseWithoutBody(statusCode: HttpStatusCode.NotFound, Summary = "Pet not found", Description = "Pet not found")]
public async Task GetPetById(
[HttpTrigger(AuthorizationLevel.Anonymous, "GET", Route = "pet/{petId}")] HttpRequest req, long petId)
{
var pet = this._fixture.Build().With(p => p.Id, petId).Create();

return await Task.FromResult(new OkObjectResult(pet)).ConfigureAwait(false);
}

public class PetIdExample : OpenApiExample
{
public override IOpenApiExample Build(NamingStrategy namingStrategy = null)
{
Examples.Add(OpenApiExampleResolver.Resolve("Bandit",
11,
namingStrategy));
return this;
}
}
```
- navigate to the swagger endpoint and view json file
e.g.
```
"/pet/{petId}": {
"get": {
"tags": [
"pet"
],
"summary": "Find pet by ID",
"description": "Returns a single pet.",
"operationId": "getPetById",
"parameters": [
{
"name": "petId",
"in": "path",
"description": "ID of pet to return",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
},
"example": 11,
"examples": {
"Bandit": {
"value": 11
}
},
"x-ms-summary": "ID of pet to return",
"x-ms-visibility": "important"
}
],
"responses": {
"200": {
"description": "successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/pet"
}
}
},
"x-ms-summary": "successful operation"
},
"400": {
"description": "Invalid ID supplied",
"x-ms-summary": "Invalid ID supplied"
},
"404": {
"description": "Pet not found",
"x-ms-summary": "Pet not found"
}
},
"security": [
{
"api_key": [ ]
}
],
"x-ms-visibility": "important"
},
```

**Expected behaviour**
Either an "example" field or "examples" field but not both.

**Screenshots**
I Initially discovered this viewing a document on [swagger](https://editor.swagger.io/)
image

**Environment (please complete the following information, if applicable):**
- Version 1.4.0

Contributor guide

Open the contributing guide

Research direction

Reproduce the issue using an OpenApiParameter with an Example, then inspect the swagger endpoint output for the generated parameter object. Validate the resulting swagger.json against the OpenAPI specification and confirm that the output contains either example or examples, not both.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.