使用Fastify Swagger时limit字段始终被标记为必填的问题求助

问题根源 #

你在路由schema里把limit和sort定义在了params字段下，但Fastify的params对应的是URL路径参数（比如/list/:limit/:sort这种带占位符的URL结构）。根据OpenAPI 3.x规范，路径参数本身就是必填项——因为它们是URL路径的一部分，缺失会导致路由无法匹配，所以Swagger会强制将其标记为必填，完全忽略你在required数组里的配置。

解决方法 #

把schema里的params替换为query，因为limit和sort明显属于URL查询参数（格式为/list?limit=10&sort=asc）。查询参数默认是可选的，只有被你加入required数组的字段才会被标记为必填。

修改后的路由代码：

export const articleRouter = async (fastify: FastifyInstance) => {
  fastify.get(
    '/list',
    {
      schema: {
        tags: ['article'],
        summary: 'getting article list',
        description: 'description in routes',
        // 将 params 替换为 query
        query: {
          type: 'object',
          description: 'some query parameters',
          properties: {
            limit: {
              type: 'number',
              description: 'limit articles'
            },
            sort: {
              type: 'string',
              description: 'asc or desc'
            }
          },
          required: ['sort']
        },
      }
    },
    async (req, resp) => {
      // 注意：参数要从 req.query 中获取，不再是 req.params
      const { limit, sort } = req.query;
      const articles = await articleService.findArticles(limit, sort);
      resp.send(articles);
    }
  );
};

额外说明 #

• 如果你确实需要把limit作为路径参数（比如路由定义为/list/:limit/:sort），那它必然是必填项，这符合RESTful设计规范，此时无法改为可选。
• Fastify里的schema字段对应不同的参数位置：params是路径参数、query是查询参数、body是请求体参数，一定要根据参数的实际类型选择正确的字段。

内容的提问来源于stack exchange，提问作者Eldar Nasyrov