Update README with OpenAPI v3 instead of Swagger example

[melroy89]

Prerequisites

• [X] I have written a descriptive issue title
• [X] I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

Update Fastify Swagger example with OpenAPI v3.

I used Swagger in the past, but I was able to set multiple hosts (aka servers) in the Swagger documentation page.

See: https://swagger.io/docs/specification/api-host-and-base-path/

For some reason Fastify Swagger-ui has a screenshot of a drop-down with servers in the README. However, I don't see any documentation how to do this. And with the host key I can only set 1 base domain.

Motivation

You should be able to provide multiple hosts with additional description. Allowing users / admins to easily switch between different servers or environments (eg. acceptance vs production URL).

Example

Example in Swagger v3.x YAML syntax:

    servers:
      - url: https://api.example.com/v1
        description: Production server (uses live data)
      - url: https://sandbox-api.example.com:8443/v1
        description: Sandbox server (uses test data)

[mcollina]

Thanks for reporting! Would you like to send a Pull Request to address this issue? Remember to add unit tests.

[melroy89]

It does seems it has maybe to do with Swagger OpenAPI v2 support that doesn't support servers. Only OpenAPI v3 spec does support that: https://swagger.io/specification/v3/

@mcollina before I create a PR, can you please explain the different of swagger vs the openapi options to me? Eg. https://github.com/fastify/fastify-swagger/blob/master/examples/options.js#L41

Since it could be that I "just" need to use "openapi" key for OpenAPI v3? Again, it's very confusing for me since the swagger key implies that this is some kind of different specification.., despite the whole point of Swagger is the native OpenAPI support.

[mcollina]

swagger is the swagger spec (or renamed as openapi v2) openapi is openapi v3.

If this works in openapi v3, you should use the openapi option.

[melroy89]

Yea. I think we all should, since OpenAPI v3 has better documentation features. I think we should update the README:

https://github.com/fastify/fastify-swagger/blob/master/README.md#usage

The readme still shows OpenAPI v2.

[melroy89]

Oef, I already found a TS type definition bug in OpenAPI-Types upstream project: https://github.com/kogosoftwarellc/open-api/pull/901. I was wondering what I was doing wrong when trying to use the OpenAPI v3 spec. I also cross-checked with your test JS file. Does the TS type definition of OpenAPI not accept a number here...

I'm trying really hard here to get my TS Fastify backend application delivered, but it has not been an easy ride thus for me (as you noticed by now by all different PR & issues from my side, sorry about that..).

[melroy89]

I created a PR to address this issue and show an OpenAPI v3 example by default under "Usage".