Support is implemented for both joi and zod to parse schema's. Currently the choice of which to use is hard coded, add a cli flag to choose between the different implementations

Currently static code snippets for helper functions are stored as inline template strings.

They would be easier to work with as normal typescript files, and then we could write unit tests directly against them rather than indirectly testing the generated output.

we currently mostly support allOf / oneOf but don't have any support for anyOf - add basic support as a union type

see https://json-schema.org/understanding-json-schema/reference/combining.html#anyof for specification, but note:

anyOf - Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.

Expected Behavior
A valid openapi: "3.1.0" document should pass initial validation against the openapi 3.1 specification without errors.

Actual Behavior
Validation fails with confusing / obtuse error messages.

Cause
It seems that ajv does not support some of the keywords used in defining the specification properly, causing it to fail:

• OAI/OpenAPI-Specification#2689
• ajv-validator/ajv#1745

The best thing to do is probably wait for ajv to improve support for $dynamicAnchor, and skip validation for 3.1 specifications in the meantime.

Currently we always type additionalProperties as Record<string, unknown> but it's possible for a more specific type to be used in some cases.

additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. Consistent with JSON Schema, additionalProperties defaults to true.

ref: https://spec.openapis.org/oas/v3.0.3#properties

currently only the typescript-koa does any runtime parsing/validation.

add support to the typescript-fetch template for validating parameters, and parsing responses using the configured schema builder (ie: zoa / joi)

Assess and document the projects completeness for support of OpenAPI 3.0.3

Submit / link to issues where there are gaps.

Hi there,

I've been looking for a way to generate a typescript server from an openapi schema that wasn't express based for a while now, and I am happy I found this tool, as it supports both Koa and Zod which are two library I have been using heavily in my projects, so big thanks for making it.

Now I am working on a project where I need to specify additional options to the Koa instance, one being the host options and the ability to use a custom function for the listen callback. Both of these are pretty important requirements for my project, due to how we want our output being presented to the console. Because my project makes use of node clusters, calling the startServer function means that every web cluster instance is now outputting the line server listening: ... which is not ideal, and there is no options to prevent this.

So having the option to override the default as a field in the ServerConfig type would be a good compromise, unless of course you have a better solution in mind.

Thanks

It's possible to declare different request bodies for different content types.

Currently we simply use the first one that we find:

At a minimum we should support:

• multipart/form-data
• application/octet-stream
• text/plain

Ideally we'd additionally support XML, but that might be left for it's own issue.

It's possible to declare response headers on the response specifications. Add support for these as per specification here: https://spec.openapis.org/oas/v3.0.3#response-object

This should definitely be it's own issue (coming from this issue) and this shouldn't be strictly related to #81.

So I have used other projects (mainly golang related) for openapi, and I was spoiled with the option of having the spec embedded into the server via base64 encoding. I'll provide this link here, that gives a good example of how that may look.

Unlike issue #81 this is not about providing documentation, but rather exposing the openapi schema itself, which can be served by the application itself, allowing someone to generate a client from that schema for the exact version of software that is hosting it. I've personally always found this way of doing it to be fitting for almost all apps that I have written using openapi.

Now I am not sure how involved you want this process to be, I personally would be fine with having it generated and a few helper functions to decode it, cache it, and then provide a function to get the cached contents of which could be served on any endpoint I wish without any forced requirements. However maybe you want the process to be more controlled, and maybe you have some function that takes an endpoint string, and then the library handles serving it up on that endpoint, with very little effort on the developer using it.

I hope this is something that makes it into the library in some way, as I see it being very beneficial.

https://typespec.io/ seems like a pretty cool alternative specification language to openapi

they have API's that transpile it to OpenAPI 3, so it should be pretty trivial to support it as alternative input specification.

(ref: https://typespec.io/docs/libraries/openapi3/reference/js-api/functions/getOpenAPI3)

separately, I've been experimenting in private with SQL database schema + query AST introspection to produce zod schemas for a given SQL query, and toying with the idea of incorporating that into this project as another input source (alternatively since that's reasonably out of scope of the current project, separating some of the components I want to reuse from here into packages might make more sense)

Having the ability to separate routes based on tags specified in the openapi schema. This would make it easier to implement routes in classes for that specific tag.

I would assume it might end up looking something like this

export type MiscEndpoints = {
  getVersion: GetVersion,
  getSpec: GetSpec,
}

export type Implementation {
  miscRoutes: MiscEndpoints ,
  // non tagged endpoint
  getInfo: GetInfo,
}

I assume this might end up requiring a little more work as to figure out that MiscRoutes implements sub routes, so I'm not sure of what the best way to do that is for this project, but hopefully this is enough information to give you an idea of what I am trying to get at.

Generally in most cases you end up having a file full of functions that implements something like /users endpoint, and you would return a router implementing those routes, but would be nice to be able to implement these routes from a class such as in my case.

Right now it's not very easy to implement from a class, cause I generally have to make another structure and target specific routes for those specific routes such as /users, and /version and /spec are misc routes.

Would like to discuss more on this topic, if you have any ideas?

Implement support for loading definition files from URI.

Should be supported for both root/entry-point file, and also for referencing external schemas, eg:

$ref: 'https://example.com/openapi.yaml#/components/responses/ClientError'

Care needs to be taken as to relative path handling. Eg: if you reference a external file using a URL, and it references a file relatively then this should be resolved relative to the URL.

See https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03 for exact specifications.

Async API is a specification for describing event driven architecture, that aims to keep near compatibility with openapi specifications:

Part of this content has been taken from the great work done by the folks at the OpenAPI Initiative. Mainly because it's a great work and we want to keep as much compatibility as possible with the OpenAPI Specification.

It would be good to investigate adding support for this, possible templates could include:

• GCP PubSub
• AWS SNS/SQS
• Azure Service Bus
• RabbitMQ
• Kafka
• ZeroMQ

https://www.asyncapi.com/docs/tutorials/getting-started/coming-from-openapi

So I ignored a few of the issues since, this project is still early, and they were only type issues that I could work around, but with version 0.3.0 another issue has cropped up that breaks things for me.

So the major issue that breaks things for me now, is the fact then after updating to 0.3.0 I am presented with

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './errors' is not defined by "exports" in /workspace/node_modules/@nahkies/typescript-koa-runtime/package.json

and the small but workaround issues that I have found since day one of using this, is also related in a way to the above, but not caused by it.

Cannot find module '@nahkies/typescript-koa-runtime/server' or its corresponding type declarations.ts(2307)
Cannot find module '@nahkies/typescript-koa-runtime/zod' or its corresponding type declarations.ts(2307)

it seems the runtime has no issues with these paths, but typescript does, and adding /src/ after @nahkies/typescript-koa-runtime path fixes the typescript issues, so it's just a simple path rewrite that needs to happen for the typescript types.

One last possible issue that I think you overlooked was you are linking joi definitions for zod.

It's possible one or more of these issues are related to my setup, so do let me know, thanks.

we don't want to accidentally overwrite peoples work

• bail out if output directory is a git repo and there are uncommitted changes
• add flag to override this behavior

Implement response validation based on status code and matching schema.

• exact status codes take priority, followed by 2xx style ones and finally the default schema
• include configuration flag to enable/disable at runtime
• support both zod and joi

• consider whether the format property can be used to improve the schema generation (ref: https://spec.openapis.org/oas/v3.0.3#data-types)
• consider whether JSON schema validation information can be used (ref: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00#section-5) eg: minimum / maximum
• consider how BigInt's might work

add support for optionally serving documentation generated using https://github.com/Redocly/redoc for servers using typescript-koa template

essentially this will involve:

• exposing a route /docs returning an html document including the redoc html below
• exposing a route /openapi.yaml returning the specification used to generate the server

the html will look similar to:

<html>
<body>
    <redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
</body>
</html>

with the spec path updated, and a sub resource integrity hash added (https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity)

this functionality should be optional, and the routes configurable to ensure that it can be used without collision with the actual API surface.

add support for the encoding object https://spec.openapis.org/oas/v3.0.3#encoding-object

So far I am passing in a generic auth middleware to validate cookies/tokens for my application and then setting the state to that of a user entity. Which so far is nothing crazy and pretty standard, but when it comes to dealing with it in the routes, I seem to be writing the same code over and over again and even if abstracted into a function I still have to remember to call that function at the top of each route call.

Should I wait for per route middleware or for security schemes to be supported or is there a better way of doing this? Ideally I would make use of the libraries security schemas to implement my logic and then have that implementation called on all the routes linked with the securitySchemas specified in the openapi file, but of course I am not yet able to do that.

Any ideas?

Hi there,

So I recently found out about https://typespec.io/ and was interested in giving it ago, and so far has been pretty interesting as well as a nice difference to writing it in yaml.

However I just found my first problem since using it, and that is that they don't allow you a way to generate additionalProperties with a yes meaning I am currently unable to use my APIError object as I previously was, and that is due to the EmptyObject that is applied, which essentially forces me to do as any every time I wish to output any metadata.

export type t_APIError = {
  error: string
  message?: string
  metadata?: {
    [key: string]: EmptyObject
  }
  suggested?: string
}

Is there a way to nicely work around this or will I need to wait for some update/change for it? For now I will just override the type checking with as any until a better solution is found.

So for example this is what I have in my openapi schema

  /v1/users/{user_id}:
    get:
      operationId: UserGetById
      description: Get a user by ID.
      tags: [users]
      parameters:
        - name: user_id
          required: true
          in: path
          schema: { $ref: '#/components/schemas/Identifier' }
      responses:
        default: { $ref: '#/components/responses/InternalServerError' }
        '404': { $ref: '#/components/responses/NotFound' }
        '401': { $ref: '#/components/responses/Unauthorised' }
        '200': { $ref: '#/components/responses/UserGetByIdOK' }

as you can see I have the parameter as user_id and the generated schema for this becomes

const userGetByIdParamSchema = z.object({ user_id: s_Identifier })

so far this all looks fine, until you look at the route that is generated

router.get("userGetById", "/v1/users/:userId", async (ctx, next) => { ... }

and now you'll notice it's checking against userId and not user_id which leads to a validation error. I'm aware I could just rename the parameter in my openapi file to match the koa parameter, but it's probably a good idea to address this, so it's not an annoying requirement.

Implement an io-ts based schema parser as an alternative to joi and zod