Azure / Azure/azure-functions-openapi-extension

Components section of Spec does not handle generics correctly

Open
#346 2 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**
We have some HTTP triggers that return various rather complex data types, often with generics or lists or nullable types. The "components" section of the OpenApi spec gets generated in a way that violates the OpenApi v3 standard. For example:

```
{
"openapi": "3.0.1",
"info": {
...
},
"version": "1.0.0.0"
},
"paths": {
...
},
"components": {
"schemas": {
...
"property_list`1": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/tag"
}
}
}
},
"property_nullable`1": {
"type": "object",
"properties": {
"value": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
},
...
```

The key name property_list`1 is not valid as per the [spec](https://swagger.io/specification/):

![image](https://user-images.githubusercontent.com/43483709/148859907-4c4ba9ce-5295-4639-b6ac-b91baeb0a428.png)

I think these names need to be encoded in a way to only use letters, numbers, periods, hyphens and underscores. The backtick should not be allowed.

**To Reproduce**
Steps to reproduce the behavior:
1. Generate an OpenApi spec involving some data types that use generics.
2. Run the spec through an OpenApi validator, such as [this one](https://validator.swagger.io/).

**Expected behavior**
All keys in the "components" section of the spec should be valid, meaning they must conform to the regular expression `^[a-zA-Z0-9\.\-_]+$.`

**Screenshots**
If applicable, add screenshots to help explain your issue.

**Environment (please complete the following information, if applicable):**
- OS: [e.g. Windows/Mac/Linux]
- Browser [e.g. edge, chrome, firefox, safari]
- Version [e.g. 22]

**Additional context**
This is important for us since we integrate OpenApi spec validators into our test automation.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.