Skip to content

Latest commit

 

History

History
46 lines (37 loc) · 1.29 KB

apiSpec.md

File metadata and controls

46 lines (37 loc) · 1.29 KB

apiSpec

Helper function for defining a collection of routes and associating them with operation names.

Usage

The intended usage is to create a top-level export that uses apiSpec to define a service's API as a collection of operations linked to routes. This function itself does not do anything aside from enforce the correct type of the parameter passed to it.

import { apiSpec } from '@api-ts/io-ts-http';

import { GetMessage, CreateMessage } from './routes/message';
import { GetUser, CreateUser, PatchUser, UpdateUser, DeleteUser } from './routes/user';

/**
 * Example service
 *
 * @version 1.0.0
 */
export const API = apiSpec({
  'api.v1.message': {
    get: GetMessage,
    post: CreateMessage,
  },
  'api.v1.user': {
    get: GetUser,
    post: CreateUser,
    put: UpdateUser,
    delete: DeleteUser,
    patch: PatchUser,
  },
});

Other packages are designed to read these API specs for various purposes such as creating a type-checked api client, binding functions to routes with automatic parsing and validating, and generating things such as an OpenAPI schema.

Metadata

Currently, if a @version JSDoc tag is added to the exported API spec, it will be used as the API version when generating an OpenAPI schema. Support for other tags may be added in the future.