Controller Annotations

[jeffreybradley1963]

I have not been able to get the Controller Annotations to work.

In my file I have tried

/** @oastools {Controller} /agent */

/**
 * @oastools {method} GET
 */
module.exports.getAgent = function .....

and I've tried

/** 
 * @oastools {Controller} /agent 
 * @oastools {method} GET
 */
module.exports.getAgent = function ...

When I run the app, I get
[oas-tools] WARN: get-agent.js has been ignored: file does not contain a valid controller annotation.

This seems to follow the documentation to the letter. My swagger file for /agent is

paths:
  '/agent':
    get:
      summary: Get upgrade agent installler
      description: Return the agent installer
      responses:
        '200':
          description: successful operation
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

[alesancor1]

Hello, I just initialized a new server with @oas-tools/cli using your OAS declaration and copied your controller, but I couldn't reproduce the error. When using annotation you must take into account that:

• The controller annotation must be always placed at the begining of the file
• The method annotation is always required right above your controller functions
• Annotations must be enabled in configuration

Below I'm leaving the files I used to try to reproduce the situation:

• Controller file

/** @oastools {Controller} /agent */

/**
 * @oastools {method} GET
 */
module.exports.getAgent  = function getAgent (req, res) {
    res.send({message: "mockup"})
}

• OAS yaml declaration

openapi: 3.0.0
info:
  version: 0.1.0
  title: Data Service
paths:
  '/agent':
    get:
      summary: Get upgrade agent installler
      description: Return the agent installer
      responses:
        '200':
          description: successful operation
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                type: string

• Framework configuration - .oastoolsrc:

{
    "packageJSON": "package.json",
    "oasFile": "api/oas.yaml",
    "useAnnotations": true,
    "logger": {
        "customLogger": null,
        "level": "info",
        "logFile": false,
        "logFilePath": "./logs/oas-tools.log"

    },
    "middleware": { 
        "router": { "disable": false, "controllers": "./controllers" },
        "validator": { "requestValidation": true, "responseValidation": true, "strict": false },
        "security": { "disable": true, "auth": null },
        "swagger": { "disable": false, "path": "/docs", "ui": { "customCss": null, "customJs": null } },
        "error": { "disable": false, "printStackTrace": false, "customHandler": null }
    }
}

I hope this can help you out, but bear in mind that annotations are experimental and may change in the future, to be more specific, they are likely to be replaced by Javascript decorators.

[jeffreybradley1963]

Thanks - I am actually trying to use TypeScript to do a proof of concept using oas-tools in a Restful API built with TypeScript. I found that my generated nodejs code had "use strict" as the first line. I put the following in the "compilerOptions" of my tsconfig.json file

    "module": "ESNEXT",
    "moduleResolution": "NodeNext"

and now it generates the .js files properly. And, the routing works perfectly as well!

Thanks!