search

FusionAuth / fusionauth-openapi

FusionAuth OpenAPI client
https://fusionauth.io/docs/v1/tech/client-libraries/openapi/
Apache License 2.0
7 stars 1 forks source link

OAS type inconsistency #1

Closed JohnCarrollSplit closed 9 months ago

JohnCarrollSplit commented 2 years ago

I have noticed a type inconsistency between the OAS docs for the API and the actual usage and example usage of the API.

This is based on the current API spec at https://github.com/FusionAuth/fusionauth-openapi/blob/master/openapi.yaml

This same issue appears across multiple components but for a concrete example in the User component expiry field:

expiry: "$ref": "#/components/schemas/ZonedDateTime"

The field reference is for a type of ZonedDateTime but the actual type is a numeric (long)

In the example response displayed on this page - https://fusionauth.io/docs/v1/tech/apis/users#reactivate-a-user - you can see that "expiry" is in fact numeric with no timezone representation and not a ZonedDateTime

robotdan commented 2 years ago

When using a typed domain such as Java - we do use a ZonedDateTime for all instants which are serialized and de-serialized as an 8 byte integer (long).

I am not an OpenAPI expert, so perhaps I need to do some more research, but since that is a component ref and we do define that component as a 64 bit integer, it seems correct to me. 

ZonedDateTime:
  description: A date-time with a time-zone in the ISO-8601 calendar system, such
        as 2007-12-03T10:15:30+01:00 Europe/Paris.
  example: '2007-12-03'
  type: integer
  format: int64

Are you suggesting it would be better if we replaced this 

insertInstant:
  $ref": "#/components/schemas/ZonedDateTime"

with this?

insertInstant:
  type: integer
  format: int64

I think there is some benefit to describing these fields as a zoned date / time because it provides some additional context to the type of 8 byte integer we are expecting.

voidmain commented 2 years ago

I think the description is incorrect though. That should state that the ZonedDateTime is always Epoch Milliseconds UTC since longs don't have a timezone component.

Is that what you were referring to @JohnCarrollSplit?

JohnCarrollSplit commented 2 years ago

Yea, the description is off, I think what you said makes sense though, just describe it as always having the timezone UTC when represented as a long

mooreds commented 9 months ago

Fixed under https://github.com/FusionAuth/fusionauth-client-builder/pull/48

Closing.