RESTful API with OpenAPI

Vovk.ts automatically generates OpenAPI specification from the defined controllers and methods. The generated client exports openapi object for composed client and for each chunk of segmented client separately.


import { UserRPC, openapi } from 'vovk-client'; // composed client


import { UserRPC, openapi } from '@/client/user/index.ts'; // segmented client

The openapi object can also be imported from vovk-client/openapi or @client/user/openapi that import the object only, without the RPC client.

The object is a ready-to-use OpenAPI specification that can be used with any tool that supports OpenAPI 3+.

You can use the object directly or create a static segment with a simple controller that exposes the spec as a JSON endpoint.


npx vovk new segment --static static


pnpm dlx vovk new segment --static static


yarn dlx vovk new segment --static static


bun x vovk new segment --static static


npx vovk new controller static/openApi --empty


pnpm dlx vovk new controller static/openApi --empty


yarn dlx vovk new controller static/openApi --empty


bun x vovk new controller static/openApi --empty

src/modules/static/openapi/OpenApiController.ts


import { get, operation } from "vovk";
import { openapi } from "vovk-client/openapi";
 
export default class OpenApiController {
  @operation({ // the operation object definition is optional
    summary: "OpenAPI spec",
    description: 'Get the OpenAPI spec for the API',
  })
  @get("openapi.json")
  static getSpec = () => openapi;
}

On the client-side you can use any OpenAPI tooling, but it’s recommended to Scalar as Vovk.ts generates code snippets that can be copied directly to your codebase.


import { ApiReferenceReact } from "@scalar/api-reference-react";
import "@scalar/api-reference-react/style.css";
 
async function App() {
  return (
    <ApiReferenceReact
      configuration={{
        url: "/api/static/openapi.json",
        servers: [
          {
            url: "http://localhost:3000",
            description: "Localhost",
          },
          {
            url: "https://example.com",
            description: "Production",
          },
        ],
      }}
    />
  );
}
 
export default App;

See what it looks like in the “Hello World” app . For more info, check the “Hello World” page.