Openapi.yaml doc for API

[mggevaer]

I created an Openapi doc, this way it's easier to generate SDK's and try out the API.
I don't think there's much more information which can be captured in the OpenAPI doc than what I've got in there now.

Some concerns.

• The enum for supported countries is hard-coded and does not auto-update with the returned value of the supported countries API call.
• Currently assumes all conversion rates have a precision of 0.0001

[mggevaer]

Let me know if anything needs to happen or looks wrong before this could be merged.

[hakanensari]

Hi @mggevaer! Thanks for contributing this.

We actually already have an OpenAPI specification at lib/public/v1/openapi.json, served at https://api.frankfurter.dev/v1/openapi.json.

Your spec has more detailed schemas, but maybe some, as you pointed out, are too rigid or could become outdated.

We could cherry-pick some of your better schema definitions to enhance the existing openapi.json while keeping the flexibility that matches actual API behavior?

[mggevaer]

Ah, I was unaware of the existing openapi doc.
I updated my openapi doc, copying schemas, naming, descriptions, etc... where possible.

During the creation of my own schema I did discover a significant fault in the existing openapi doc.

It's not convention for path parameters to be optional, as is the case with /start_date...end_date.
However, because end_date is optional, it's marked as "required": false, which makes the openapi doc invalid.
Luckily this can be solved with a workaround that doesn't require code changes.
We can simply split up the openapi definition for this endpoint into 2 paths:
/start_date...
and
/start_date...end_date

Some other changes I made:

• Schema's get a lowercase name, this is to avoid conflicts with the built in JS "Date" object, when defining a schema named "date"
• Mark many values as "required", where it's reasonably expected that they are required, or if missing lead to errors. This makes a major difference during code generation when working with something like typescript. It avoids having to do optional checks when in reality values some value are always part of responses.
• Replaced date example from 2024-01-01 to 2024-01-15 to further clarify that the last numbers are the days.
• ... bunch of other stuff I've forgotten about.

Overall I've copied existing information where possible, and added where possible.
If you copy the file into something like swagger editor you'll notice the documentation has been expanded quite a bit.
I'm also seeing higher quality code when generating an SDK through Openapi generator.

If this gets merged I can update my code generating to pull the latest openapi doc each time, which would avoid some fragility if breaking changes come through down the line.

[hakanensari]

Looks great, thanks for the overhaul @mggevaer!