Add ability to filter by version constraint

[Liam-Tait]

Prerequisites

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

🚀 Feature Proposal

When generating a specification I want to be able to filter by the API version constraint so I can have multiple schema files with specific versions associated. For example, a schema for version 1 routes and version 2 routes.

There are two ways of adding this that come to mind:

Add a specific filter for the version constraint to the Options object

This approach makes it easy to integrate with find-my-way versioned routes using the same server logic. The options object would have an additional property such as apiVersion with a semver string that filters for only routes that match the server.

Allow a route's constraints to be accessed within the transform function

This would give users the option to use any constraint to to modify the schema, for version constraints this would be adding a step within the transform function to add the. Maximum flexibility but means it's user land code to ensure the versioning logic matches with find-my-way

Motivation

When creating an API I would like to generate several API specifications, one for each major version.

Example

await fastify.register(require('@fastify/swagger'), {
  openapi: { ... },
  apiVersion: "1.0.0"
})

or

await fastify.register(require('@fastify/swagger'), {
  swagger: { ... },
  transform: ({ schema, url, constraints }) => {
    if (!semver.satisfies(constraints.version, "1.0.0")) {
      schema.hide = true
    }
    return { schema, url }
  }
})

[mcollina]

This would be a nice feature to add. Would you like to send a PR?