Fastify 3.x how to tag my routes ? To be visible in sections under swagger in fastify-oas

[andersakerberg]

Hello,

First let me start out with thanking you for your awesomeness , I love everything you do!

I am coming from fastify 2.x and was using fastify-oas to structure my swagger documentation, I have now tried to migrate to fastify 3.x and trying to acheive the same outcome here, is it possible? What am I doing wrong ? :)

from routes/organization/getOrganization

export const opts: RouteShorthandOptions = {
  schema: {
    params: baseParamsSchema,
    response: {
      200: organizationSchema,
    },
  },
  //@ts-ignore
  tags: ["organization"],
  preValidation: [],
  preHandler: [],
};

from server.ts

server.register(swagger, {
  routePrefix: "/docs",
  exposeRoute: true,
  swagger: {
    basePath: "/",
    info: {
      title: "Marketeer core swagger",
      version: pj.version,
      description: swaggerDescription,
    },

    host: "localhost",
    schemes: ["http"],
    consumes: ["application/json"],
    produces: ["application/json"],
    definitions: getSwaggerDefinitions(),
    securityDefinitions: {
      JWT: {
        type: "http",
        scheme: "bearer",
        bearerFormat: "jwt",
      },
    },
    tags: [{ name: "organization" }],
  },
  uiConfig: {
    docExpansion: "full",
    deepLinking: false,
  },
});

What was the result you received?

They dont get folder within their respective tags

What did you expect?

I want my routes to be folded under their respective tags

Context

• node version: v15.12.0
• fastify version: >=^3.14.0
• • fastify-oas: ^3.0.8
• os: Windows, Ubuntu WSL
  Please read this entire template before posting any issue. If you ignore these instructions
  and post an issue here that does not follow the instructions, your issue might be closed,
  locked, and assigned the missing discussion label.

[mcollina]

I don't really understand what is the problem or what you are trying to achieve.

Maybe @climba03003 can help!

[climba03003]

I don't know why you use @ts-ignore in the TypeScript. If you use TypeScript and it throw you an error, there should be something wrong in your code.

fastify-swagger and fastify-oas only touch the schema part of route options. So, the valid example is in below.

export const opts: RouteShorthandOptions = {
  schema: {
    tags: ["organization"],
    params: baseParamsSchema,
    response: {
      200: organizationSchema,
    },
  },
  preValidation: [],
  preHandler: [],
};

Example of fastify-oas
Example of fastify-swagger

[L2jLiga]

Yeah, I can confirm that both libraries works well when you specify tags inside scheme

[andersakerberg]

export const opts: RouteShorthandOptions = {
  schema: {
    tags: ["organization"],
    params: baseParamsSchema,    
    response: {
      200: organizationSchema,
    },
  },
 
  preValidation: [],
  preHandler: [],
};

Above works but still gives error, I will @ts-ignore meanwhile, error is :

Type
{ tags: string[]; 
    params: { 
      description: string; 
      type: string; 
      properties: { 
          organizationId: {    
              type: string; 
              title: 
              string; 
          }; 
      }; 
    required: string[]; $schema: string; };
    response: { 
        200: { 
            description: string; 
            type: string; 
            properties: { ...; };
            required: string[]; 
            $schema: string; 
          
        }; 
      
    }; 
}
is not assignable to type 'FastifySchema'.
Object literal may only specify known properties, 
and 'tags' does not exist in type 'FastifySchema'.

[andersakerberg]

I don't know why you use @ts-ignore in the TypeScript. If you use TypeScript and it throw you an error, there should be something wrong in your code.

fastify-swagger and fastify-oas only touch the schema part of route options. So, the valid example is in below.

export const opts: RouteShorthandOptions = {
  schema: {
    tags: ["organization"],
    params: baseParamsSchema,
    response: {
      200: organizationSchema,
    },
  },
  preValidation: [],
  preHandler: [],
};

Example of fastify-oas
Example of fastify-swagger

Yes I was only using it because unsure where to put it, sometimes some type is missing and @ts-ignore helps more then u would know. Am I missing some explicitly installed types here? Full package.json

{
  "name": "marketeer.core.api",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "build": "tsc -p tsconfig.json",
    "start": "node index.js",
    "generate:schemas": "npx ts-node src/generateSchemas.ts",
    "dev": "cross-env NODE_PATH=src TS_NODE_FILES=true nodemon src/server.ts"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/marketeer-app/marketeer.core.api.git"
  },
  "author": "",
  "license": "ISC",
  "bugs": {
    "url": "https://github.com/marketeer-app/marketeer.core.api/issues"
  },
  "homepage": "https://github.com/marketeer-app/marketeer.core.api#readme",
  "dependencies": {
    "app-module-path": "^2.2.0",
    "cross-env": "^7.0.3",
    "dotenv": "^8.2.0",
    "fastify": "^3.14.0",
    "fastify-caching": "^6.1.0",
    "fastify-cors": "^5.2.0",
    "fastify-helmet": "^5.3.1",
    "fastify-oas": "^3.0.8",
    "nodemon": "^2.0.7",
    "pino-pretty": "^4.7.1",
    "prettier": "^2.2.1",
    "typescript-json-schema": "^0.50.0",
    "uuid": "^8.3.2"
  },
  "devDependencies": {
    "@types/node": "^14.14.35",
    "@typescript-eslint/eslint-plugin": "^4.18.0",
    "@typescript-eslint/parser": "^4.18.0",
    "eslint": "^7.22.0",
    "typescript": "^4.2.3"
  }
}

[climba03003]

I see the problem.
https://github.com/SkeLLLa/fastify-oas/commits/master

The type for route schema is using the fastify@2 typings. And it do have a commit resolving it for fastify@3 but it is not released.

Can you open an issue for fastify-oas to address this problem? or migrate to fastify-swagger.

[andersakerberg]

I see the problem.
https://github.com/SkeLLLa/fastify-oas/commits/master

The type for route schema is using the fastify@2 typings. And it do have a commit resolving it for fastify@3 but it is not released.

Can you open an issue for fastify-oas to address this problem? or migrate to fastify-swagger.

New issue open here SkeLLLa/fastify-oas#68