node.js - Fastify Swagger, ajouter une étiquette et une description à une route Fastify

J'utilise fastify 3.28.0 (plus le plugin fastify-swagger) avec TypeScript 4.6.2, et j'aimerais ajouter des tags, une description et un résumé dans chaque route.

D'après les documents : fastify swagger Il serait possible d'ajouter une description, des étiquettes et un résumé à chaque route.

Mais je ne peux pas le faire parce que la définition du schéma ne les fournit pas :

export interface FastifySchema {
  body?: unknown;
  querystring?: unknown;
  params?: unknown;
  headers?: unknown;
  response?: unknown;
}

Donc dans ce cas, je ne sais pas comment les définir à l'intérieur des routes Fastify :

const userRoutes: FastifyPluginCallback = (fastify, _opts, done) => {
  const findRoute: RouteOptions = {
    method: 'GET',
    url: '/:username',
    schema: {
      params: schemaParams,
      response: {
        200: schema
      }
    },
    handler: (request: FastifyRequest<{
      Params: UserRequestFindParams,
    }>, reply) => {
      const user = find(request.params.username)
      reply.send(user)
    }
  }

    fastify.route(findRoute)

    done()
}

*** MISE À JOUR

Je viens de découvrir qu'une nouvelle version de fastify-swagger a été publiée (fastify-swagger a été remplacé par @fastify/swagger). Avec la nouvelle version, toutes les propriétés mentionnées ci-dessus sont disponibles.

Réponse #1

1. Avec la version de fastify égale à "4.21.x"
2. Exécutez la commande fastify generate project;cd project; npm i
3. Créez un fichier plugins/swagger.js

const fp = require('fastify-plugin')

module.exports = fp(async function (fastify, opts) {
  await fastify.register(require('@fastify/swagger'), {
    swagger: {
      info: {
        title: 'Admin Api',
        description: 'admin api',
        version: '0.1.0',
      },
      basePath: '',
      schemes: ['http', 'https'],
      consumes: ['application/json'],
      produces: ['application/json'],
      securityDefinitions: {
        Authorization: {
          description: 'Authorization header token, sample: "Bearer #TOKEN#"',
          type: 'apiKey',
          name: 'Authorization',
          in: 'header'
        }

      }
    },
  })
  await fastify.register(require('@fastify/swagger-ui'), {
    routePrefix: '/docs',
    uiConfig: {
      docExpansion: 'none', // expand/not all the documentations none|list|full
      deepLinking: true
    },
    uiHooks: {
      onRequest: function (request, reply, next) {
        next()
      },
      preHandler: function (request, reply, next) {
        next()
      }
    },
    staticCSP: false,
    transformStaticCSP: (header) => header,
    exposeRoute: true,

  })

  fastify.addHook('onRoute', (routeOptions) => {
    if (routeOptions.schema && routeOptions.url == '/graphql') {
      routeOptions.schema.hide = true
    }
  });
});

4. Créer un nouveau fichier routes/test.js

'use strict'

const fastify = require('fastify')();

const schemaPostList = {
  description: 'Admin Post List',
  tags: ['Admin'],
  summary: 'Admin Post List',
  security: [{ "Authorization": []}],
  querystring: {
    page: { type: 'number' },
    user: { type: 'string' }
  },
};
const schemaPostDetail = {
  description: 'Admin Post Detail',
  tags: ['Admin'],
  summary: 'Admin Post Detail',
  security: [{ "Authorization": []}]
};

module.exports = async function (fastify, opts) {
  fastify.get('/list', {schema:schemaPostList},async function (request, reply) {
    return 'this is an example'
  });
}

5. Exécuter la commande npm run dev

Ça ressemble à :