API Testing

Morphis ships two complementary tools for testing your API locally:

• morphis route:list — a CLI command that prints every registered route, its HTTP verb, action name, and attached middleware
• morphis-scalar — a standalone preview server that reads your OpenAPI document and serves an interactive Scalar UI where you can call endpoints directly from the browser

Inspect routes in the terminal

Run route:list at any time without starting the dev server:

morphis route:list --server=api --format=table

Example output for the my-backend project with a PostController:

Domain | Method | Endpoint   | Action                | Middleware
-------+--------+------------+-----------------------+---------------------------------------------------
api    | GET    | /          | <anonymous>           | LoggerMiddleware, TrackMiddleware, CorsMiddleware
api    | GET    | /posts     | postController.list   | LoggerMiddleware, TrackMiddleware, CorsMiddleware
api    | GET    | /posts/:id | postController.get    | LoggerMiddleware, TrackMiddleware, CorsMiddleware
api    | POST   | /posts     | postController.create | LoggerMiddleware, TrackMiddleware, CorsMiddleware
api    | PUT    | /posts/:id | postController.update | LoggerMiddleware, TrackMiddleware, CorsMiddleware
api    | DELETE | /posts/:id | postController.delete | LoggerMiddleware, TrackMiddleware, CorsMiddleware

Other available formats:

morphis route:list --server=api --format=json      # machine-readable JSON
morphis route:list --server=api --format=openapi   # full OpenAPI 3.1 document

Interactive preview with morphis-scalar

morphis-scalar is a separate package that keeps API preview tooling outside the Morphis runtime. Pull it once alongside your project:

git clone https://github.com/kentng201/morphis-scalar
cd morphis-scalar
bun install

/
├── morphis-scalar/
└── my-backend/
    ├── src/
    │   └── routes/
    │       └── api.ts
    └── .env.api

morphis new my-backend
cd my-backend
bun install

cd ../morphis-scalar
bun run preview --project=../my-backend --server=api --open

Trying an endpoint

1 — Expand an endpoint

Click any route in the sidebar to navigate to its detail view. Scalar renders the full schema directly from your @Validate decorators. Take POST /posts as an example:

import { Validator, type SimpleValidationRuleMap } from 'morphis';
 
export type PostBody = { title: string; body: string; status: string };
 
export class PostBodyValidator extends Validator<PostBody> {
    getSimpleRules(): SimpleValidationRuleMap<PostBody> {
        const { Required, Length, In } = this.rules;
        return {
            title:  [Required, Length(255)],
            body:   [Required, Length(10000)],
            status: [Required, In('draft', 'published', 'archived')],
        };
    }
}

import { Controller, type Request, Post, Validate } from 'morphis';
import { PostBodyValidator } from '../validators/PostBodyValidator';
 
@Controller('posts')
export class PostController {
    @Post()
    @Validate({ body: PostBodyValidator })
    async create(req: Request) {
        return req.body;
    }
}
 
export default new PostController();

Scalar turns each rule into its OpenAPI equivalent automatically — no separate schema file needed:

The result in the UI:

• body — string · max 10 000 · required
• status — string · enum (draft / published / archived) · required
• title — string · max 255 · required
• Curl snippet — pre-filled with the current body shape so you can copy and run it immediately
• Test Request button — opens the interactive sending panel

2 — Send a request

Click Test Request to open the interactive panel. The form is pre-populated with all required fields and the first enum value as the default:

• Headers — accept: */* and content-type: application/json are pre-filled automatically
• Request Body — a live JSON editor pre-populated with body, status: "draft", and title
• Send — fires the request against http://localhost:3000 and streams the response on the right

Testing against a remote server

By default, Scalar points requests at http://localhost:3000 (the value of PORT in your .env.api). To test a staging or production server, set HOST — or one of the more specific overrides — in the same env file.

Using HOST

NAME=api
PORT=3000
MULTI_THREAD=true
 
HOST=api.example.com

Morphis builds the server URL as http://<HOST>:<PORT>, so the above produces http://api.example.com:3000. To use HTTPS and omit the port, add PROTOCOL and leave PORT blank (or set EXPOSE_PORT):

NAME=api
PORT=443
MULTI_THREAD=true
 
HOST=api.example.com
PROTOCOL=https

This produces https://api.example.com.

Using EXPOSE_URL (full URL override)

For the simplest override, set a complete URL — this takes priority over all other variables:

EXPOSE_URL=https://api.example.com/v1

Variable priority

Morphis resolves the OpenAPI servers[].url in this order — first match wins: