feat(openapi-generator): take and parse @example tags on JSDoc

[ekorenblum-simtlix]

The OpenAPI generator module will now accept @example tags in the JSDoc, which will translate into OpenAPI examples.
They may be used in the route definition to declare a response example, or in a schema definition to declare a schema usage example

Usage:

Schema definition

Given the following JSDoc schema definition

/**
 * A variable with example
 * 
 * @example foo
 */

The resulting YAML declaration will be

summary: A variable with example
tags:
  example:
    test: foo

Endpoint definition

Given the following endpoint definition

import * as t from 'io-ts';
import * as h from '@api-ts/io-ts-http';

/**
 * A simple route
 *
 * @operationId api.v1.test
 * @tag Test Routes
 * @example {
 *   "test": "bar"
 * }
 */
export const route = h.httpRoute({
  path: '/foo',
  method: 'GET',
  request: h.httpRequest({}),
  response: {
    200: {
      test: t.string
    }
  },
});

The resulting YAML declaration will be

openapi: 3.0.3
info:
  title: Test
  version: 1.0.0
paths:
  "/foo":
    get:
      summary: A simple route
      operationId: api.v1.test
      tags:
      - Test Routes
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  test:
                    type: string
                required:
                - test
              example:
                test: bar
components:
  schemas: {}

[bitgopatmcl]

Please re-word the commit message to use feat(openapi-generator) rather than feature(openapi-generator) since the latter won't be picked up by semantic-release.

[bitgopatmcl]

Technically this is unsound since example is a possible key of the record type so the final type should be the intersection of string & unknown which is just string

However, the compiler does treat this in the intended manner of "example could be anything, all other properties are strings". If you want the type to be more accurate you could write Record<Exclude<string, 'example'>, string> & { example?: unknown } but it doesn't appear to make a difference in practice.

[ekorenblum-simtlix]

Good catch! I changed it in the declaration as requested

[bitgopatmcl]

Can we add a test for tags that come after a multi-line example?

[ekorenblum-simtlix]

Added!

[github-actions]

🎉 This PR is included in version @api-ts/openapi-generator@3.6.0 🎉

The release is available on npm package (@latest dist-tag)

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version @api-ts/express-wrapper@1.0.26 🎉

The release is available on npm package (@latest dist-tag)

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version @api-ts/superagent-wrapper@1.2.1 🎉

The release is available on npm package (@latest dist-tag)

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version @api-ts/typed-express-router@1.1.6 🎉

The release is available on npm package (@latest dist-tag)

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version @api-ts/io-ts-http@3.1.0 🎉

The release is available on npm package (@latest dist-tag)

Your semantic-release bot 📦🚀