Azure / Azure/azure-functions-openapi-extension

Question/issue with supporting NodaTime or other custom types

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

Description

This is a question/issue around attempting to support custom types.

When attempting to support a library such as NodaTime, I run into multiple issues.

Using the DataType attribute with DataType.Date doesn't help as even though the schema "format" is set to "date", the "type" is still set to "object".

I can't see any way to support custom types otherwise.

Please add a way to specify custom types easily such as the way this library does it, simply specifying the type and format directly.
https://github.com/domaindrivendev/Swashbuckle.AspNetCore#override-schema-for-specific-types

I have an example object where I have tried a few different methods to get it to work.
The only methods that seem to work are converting it to string before storing in the object, which isn't ideal.
Or using an extra property and using JsonIgnore on the typed property.

Model
```cs
public class DateOfBirth
{
[DataType(DataType.Date)]
public string Value { get; set; } = string.Empty;

[DataType(DataType.Date)]
public DateTime DateTime { get; set; }
[DataType(DataType.Date)]
public DateTimeOffset DateTimeOffset { get; set; }
[DataType(DataType.Date)]
public LocalDate LocalDate { get; set; }

[JsonIgnore]
public LocalDate LocalDate2 { get; set; }

[JsonProperty("LocalDate2")]
[DataType(DataType.Date)]
public string LocalDateExtJson => LocalDate2.ToString("yyyy-MM-dd", null);
}
```

swagger.json
```json
"dateOfBirth": {
"type": "object",
"properties": {
"value": {
"type": "string",
"format": "date"
},
"dateTime": {
"type": "string",
"format": "date"
},
"dateTimeOffset": {
"type": "string",
"format": "date"
},
"localDate": {
"$ref": "#/components/schemas/localDate"
},
"LocalDate2": {
"type": "string",
"format": "date"
}
},
"description": "Nullable"
},
```

API response (arbitrary date values)
```json
"dateOfBirth": {
"value": "1991-03-08",
"dateTime": "2000-01-01T00:00:00",
"dateTimeOffset": "2000-01-01T00:00:00+00:00",
"localDate": "2000-01-01",
"LocalDate2": "2000-01-01"
}
```

Having to use the extra properties as a work around is very ugly.
Is there any current alternative?

There also seems to be a bug with the schema generation as the `/components/schemas/localDate` schema is not generated.
This error is displayed at the top of the page.
```
Errors

Resolver error at components.schemas.dateOfBirth.properties.localDate.$ref
Could not resolve reference: Could not resolve pointer: /components/schemas/localDate does not exist in document
```

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the example DateOfBirth model with NodaTime's LocalDate and inspect the generated swagger.json, especially the localDate reference and its missing components schema. Done means custom types can be configured with an explicit type and format without workaround properties, and all generated references resolve in the OpenAPI document.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, openapi
Domain
api
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.