CODEWITHSUNDEEP
node.jstypescriptazure-functionsswaggeropenapi
avenmia
avenmia

Reputation: 2615

How to generate openAPI spec in code for azure functions using the node sdk?

I have an api defined in azure functions that I would like to annotate in a way that can generate an openAPI spec.

I've tried using tsoa, but it doesn't seem compatible with serverless. Currently the openAPI spec is getting generated using swagger-jsdoc, but having the descriptors in comments is not maintainable. I'd like something similar to how swagger on the .NET side works, where I can annotate a function with route information and a library would generate the openAPI spec. Does this exist for typescript? I've also looked at Azure's API management to generate the spec, but the functions are currently not part of a function app (they're deployed as part of a static site's api) and I'm not sure if api management would be able to handle the typescript types.

Here is an example of my current setup with defining the spec using swagger-jsdoc.

/**
 * @swagger
 *  /api/user:
 *    get:
 *      tags:
 *      - user
 *      summary: Get the user by Id
 *      description: "Returns a single user"
 *      parameters:
 *      - in: "query"
 *        name: "id"
 *        description: "ID of the user to return"
 *        required: true
 *        schema:
 *          type: "string"
 *      responses:
 *        '200':
 *          description: OK
 *          content:
 *            application/json:
 *              schema:
 *                $ref: "#/components/schemas/User"
 *    post:
 *      tags:
 *        - user
 *      summary: POST a user to the database
 *      description: User that needs to be added to the database
 *      requestBody:
 *        description: User that needs to be added to the database
 *        content:
 *          application/json:
 *            schema:
 *              $ref: '#/components/schemas/User'
 *        required: true
 *      responses:
 *        '200':
 *          description: OK
 *          content:
 *            application/json:
 *              schema:
 *                $ref: '#/components/schemas/User'
 *
 * components:
 *   schemas:
 *    User:
 *      type: object
 *      properties:
 *        id:
 *          type: string
 *        name:
 *          type: string
 *
 * @param context The context
 * @param req The request
 */

const props: HandlerProperties<User> = {
    containerType: config.userContainer
};

export const httpTrigger: AzureFunction = async function (context: Context, req: HttpRequest): Promise<void> {
    context.res = await handleRequest(toRequest<User>(req), props);
};

export default httpTrigger;

Upvotes: 4

Views: 2159

Answers (1)

Aleksey Khorev
Aleksey Khorev

Reputation: 141

According to my investigation, there are still no plugin\way which can support it out of the box. Also the answer on the same topic. What I did for now is linked my azure functions app with APIM in azure and after downloaded generated schema from there. After I will update the schema manually and after redeploy to APIM during deployment process.

Upvotes: 7

Related Questions