typespec-openapi

Specification documents and API documentation for polyproto, polyproto-chat and polyproto-mls.

API documentation built with TypeSpec.

Pre-compiled OpenAPI schema(s)

Find the pre-compiled OpenAPI v3.1 schema file(s) in the /build directory. The schema is automatically built and deployed to the main branch on every push to the main branch.

Contributing

The best way to contribute is to open an issue if you find any problems with the documentation. Creating an issue is generally the best way to contribute to any open source project. Issues allow for an exchange between contributors and maintainers to discuss the viability of implementing an issue, usually minimizing frustration.

You should also read our Code of Conduct and Contributing Guidelines before contributing.

Setting up a development environment

nix

If you have direnv installed, create a .envrc file in the project root, containing

use flake

and run direnv allow in a shell, in the project root.

The flake provides a devshell, accessible as usual with nix develop.

Build

Build individual specifications or everything at once:

nix build .#core   # Build polyproto-core OpenAPI schema
nix build .#mls    # Build polyproto-mls OpenAPI schema
nix build .#chat   # Build polyproto-chat OpenAPI schema
nix build          # Build all specifications

Output files are placed in $PROJECT/result/.

Format

nix fmt

Check

nix flake check

Everyone else

You will need the following things installed on your computer:

• Node.js 24
• npm
• git
• TypeSpec - install it globally with npm install -g @typespec/compiler

Build

1. Navigate to the /polyproto directory.
2. Select the project you want to compile. In this example, we are compiling the core project. Navigate to that directory.
3. Run tsp install to install the dependencies.
4. Run tsp compile . to compile the project or tsp compile --watch . to automatically recompile the project when you save a file.
5. The compiled OpenAPI 3 schema should be in the $PROJECT/tsp-output/@typespec/openapi3 directory.

Format

tsp format "**/*.tsp"

Check

tsp format --check "**/*.tsp"
tsp compile ./polyproto/[chat|core|...] --dry-run