Azure / Azure/azure-functions-openapi-extension
Example for an OpenApiParameter leads to a 'structural error' validation error in the generated swagger.json
- 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/)

**Environment (please complete the following information, if applicable):**
- Version 1.4.0
Contributor 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