At Markprompt, we take developer experience seriously. That’s why we’ve invested in building a robust API documentation system that’s both comprehensive and automatically generated from our actual codebase. In this blog post, we share how we leverage Effect Schema and OpenAPI to create our API documentation fully automatically.

The challenge with API documentation

API documentation is critical for our adoption, but it often suffers from two major problems:

1. Documentation drift - As code evolves, documentation becomes outdated
2. Inconsistent information - Parameter requirements, types, and examples aren’t consistently documented

We wanted to solve these problems once and for all by generating our API documentation directly from our code. This ensures that our documentation is always in sync with our actual implementation and provides a consistent experience for developers. This was not possible before Effect.

Enter Effect Schema

Effect is a powerful library for building robust TypeScript applications, and we are using it end-to-end at Markprompt as the backbone of our scalable agent infrastructure. One of its standout features is its Schema system. Effect Schema provides a way to define, validate, and transform data, and is the foundations for how we model data types and models in our system.

Here’s a simple example of a Schema that defines the input type of our public /search API endpoint:

1// Definition of query parameters with annotations
2export const SearchUrlParams = S.Struct({
3  query: S.String.annotations({
4    description: 'The search query string.',
5    examples: ['Transactions'],
6  }),
7  limit: S.optional(S.NumberFromString).annotations({
8    description: 'The maximum number of results to return.',
9    default: 4,
10  }),
11  includeSectionContent: S.optional(
12    BooleanFromString.annotations({
13      description:
14        'Whether to return the full content of matching sections, in addition to snippets.',
15    }),
16  ),
17  debug: S.optional(
18    BooleanFromString.annotations({
19      description: 'Include debug logs.',
20    }),
21  ),
22});

The beauty of this approach is that we get both compile-time validation and documentation in one go. Each parameter is strongly typed, with optional parameters clearly marked, and everything is annotated with descriptions and examples that flow directly into our API docs.

Building the HTTP API with Effect

To build our API endpoints, we use the @effect/platform package, which provides a clean, type-safe way to define HTTP APIs:

1export class SearchApi extends HttpApiGroup.make('search').add(
2  HttpApiEndpoint.get('getSearchResults', '/search')
3    .addSuccess(SearchResultsResponse)
4    .setUrlParams(SearchUrlParams)
5    .middleware(AuthorizationMiddleware)
6    .annotateContext(
7      OpenApi.annotations({
8        title: 'Search API',
9        description: 'Get search results for a query.',
10      }),
11    ),
12) {}

Each endpoint is defined with:

• A clear HTTP method and path
• Expected success response schema
• URL parameters schema
• Middleware for authentication and validation
• OpenAPI annotations for documentation

Generating OpenAPI specifications

The magic happens when we combine Effect Schema with OpenAPI. The @effect/platform package provides an OpenAPI module that can automatically generate OpenAPI specifications from our Effect Schema definitions:

1// Create an OpenAPI spec from our API
2const openApiJsonEndpoint = HttpApiBuilder.Router.use((router) =>
3  Effect.gen(function* () {
4    const { api } = yield* HttpApi.Api.pipe(
5      Effect.provide(
6        HttpApiBuilder.api(OpenApiExposedPublicApi) as Layer.Layer<
7          HttpApi.Api,
8          never,
9          never
10        >,
11      ),
12    );
13    const spec = OpenApi.fromApi(api);
14    const response = yield* HttpServerResponse.json(spec);
15    yield* router.get('/openapi', Effect.succeed(response));
16  }),
17);

This code generates a complete OpenAPI specification at the /openapi endpoint, which includes all the endpoint definitions, parameter requirements, response schemas, and documentation annotations we’ve defined throughout our codebase.

Rendering the documentation with Scalar

Once we have our OpenAPI specification, we use Scalar ’s excellent React component to transform it into a beautiful, interactive API documentation interface:

1<ApiReferenceReact
2  configuration={{
3    spec: { url: `${publicApiUrl}/openapi` },
4    servers: [{ url: publicApiUrl }]
5  }}
6/>

Scalar provides:

• Beautiful, responsive UI - A clean, modern interface for exploring our API
• Search functionality - Find endpoints quickly with instant local search
• Code samples in multiple languages - Automatically generated examples in JavaScript, Python, cURL, and more
• Interactive playground - You can test API calls directly in the documentation

The benefits of this approach

By generating our API documentation from code, we’ve gained several major benefits:

1. Always up-to-date - Our documentation automatically stays in sync with our implementation
2. Type safety - We get compile-time validation and type checking for free
3. Consistency - Every endpoint follows the same documentation structure
4. Zero maintenance overhead - We don’t need to update documentation separately from code

Schema annotations for rich documentation

One of the key features that makes our documentation so comprehensive is Effect Schema’s annotation system. We use annotations to provide detailed information about each parameter and response field:

1// Example with annotations for parameter descriptions and defaults
2export const RetrieveSectionsParams = S.Struct({
3  prompt: S.String.annotations({
4    description: 'The input prompt.'
5  }),
6  sectionsMatchCount: S.optionalWith(
7    S.NumberFromString.annotations({
8      description: 'The number of sections to retrieve.',
9    }),
10    { default: () => 15 },
11  ),
12  sectionsMatchThreshold: S.optionalWith(
13    S.NumberFromString.annotations({
14      description:
15        "The similarity threshold between the input prompt and selected sections. The higher the threshold, the more relevant the sections. If it's too high, it can potentially miss some sections.",
16    }),
17    { default: () => 0.75 },
18  ),
19  // ...
20});
21
22// Example with annotations for example responses
23export const InfoResponseData = S.Struct({
24  id: S.String.pipe(
25    S.annotations({ examples: ['123e4567-e89b-12d3-a456-426614174000'] }),
26  ),
27  name: S.String.pipe(
28    S.annotations({ examples: ['My Project'] }),
29  ),
30  slug: S.String.pipe(
31    S.annotations({ examples: ['my-project'] }),
32  ),
33  // ...
34});

Combined with annotations, our schemas provide all the information needed for a comprehensive OpenAPI specification:

• The exact types of each parameter
• Which parameters are required versus optional
• Default values for optional parameters
• Descriptions of each parameter’s purpose and behavior
• Example output for code samples

All of this information is now automatically included in our OpenAPI specification and rendered nicely by Scalar.

Versioning our API

Another powerful feature of our setup is API versioning. We use Effect Schema to define versioned schemas for our API:

1const ChatPayload = Versioned({
2  '2024-05-21': ChatCompletionsParams,
3});

This allows us to maintain backward compatibility while evolving our API. Each version is fully documented.

Conclusion

By combining Effect Schema, OpenAPI, and Scalar, we’ve created an API documentation system that’s:

• Accurate - Always in sync with our actual implementation
• Comprehensive - Detailed information about every endpoint, parameter, and response
• Interactive - Developers can explore and test the API directly in the documentation
• Maintainable - Documentation updates automatically when we change our code

If you’re building an API, we highly recommend this approach. At Markprompt, we’re focused on building AI agents that streamline customer support, but our API documentation system is a perfect example of how a well-designed, type-safe, deterministic approach can also provide powerful automation. By investing in these foundational systems, we’ve eliminated an entire category of work, allowing our team to move fast and focus on shipping features rather than maintaining them.

Explore our API documentation to see the result in action, and check out Effect Schema and Scalar to learn more about the tools we use.