Exporting API specifications

Apicentric can export your service definitions to various formats, making it easy to generate documentation, client code, and share your APIs with other tools.

Available export formats

OpenAPI 3.0: Standard API documentation format
Postman Collections: Import into Postman or Insomnia
TypeScript Types: Type-safe interfaces for frontend code
React Query Hooks: Ready-to-use data fetching hooks
React Components: Auto-generated view components
Axios Clients: HTTP client with type safety

Exporting to OpenAPI

Convert your Apicentric service to an OpenAPI 3.0 specification:

apicentric simulator export \
  --input services/users-api.yaml \
  --output openapi.json \
  --format openapi

What gets exported

All endpoints with methods and paths
Response schemas and status codes
Request body schemas
Path, query, and header parameters
Response examples
API metadata (title, version, description)

Example export

Given this Apicentric service:

users-api.yaml

name: Users API
version: "1.0.0"
description: User management API
server:
  port: 9000
  base_path: /api/v1
endpoints:
  - method: GET
    path: /users
    description: List all users
    responses:
      200:
        content_type: application/json
        body: |
          [
            {"id": 1, "name": "Alice"},
            {"id": 2, "name": "Bob"}
          ]
  - method: POST
    path: /users
    description: Create a new user
    request_body:
      content_type: application/json
      schema: |
        {
          "name": "string",
          "email": "string"
        }
    responses:
      201:
        content_type: application/json
        body: '{"id": 3, "name": "Charlie"}'

Apicentric generates:

openapi.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Users API",
    "version": "1.0.0",
    "description": "User management API"
  },
  "servers": [
    {
      "url": "http://localhost:9000/api/v1"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "summary": "List all users",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "example": [
                  {"id": 1, "name": "Alice"},
                  {"id": 2, "name": "Bob"}
                ]
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a new user",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {"type": "string"},
                  "email": {"type": "string"}
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "example": {"id": 3, "name": "Charlie"}
              }
            }
          }
        }
      }
    }
  }
}

Exporting to Postman

Create a Postman collection:

apicentric simulator export \
  --input services/users-api.yaml \
  --output postman-collection.json \
  --format postman

Import into Postman:

Open Postman

Launch the Postman desktop app or web version.

Import collection

Click Import → Choose Files → select postman-collection.json

Test endpoints

All endpoints will be organized in folders. Click Send to test each request.

Generating TypeScript types

Export type-safe TypeScript interfaces:

apicentric simulator export-types \
  --input services/users-api.yaml \
  --output src/types/api.ts

Generated TypeScript:

src/types/api.ts

// Generated by Apicentric
// Source: services/users-api.yaml

export interface User {
  id: number;
  name: string;
  email?: string;
}

export interface CreateUserRequest {
  name: string;
  email: string;
}

export interface CreateUserResponse {
  id: number;
  name: string;
}

export interface UsersApiClient {
  getUsers(): Promise<User[]>;
  createUser(data: CreateUserRequest): Promise<CreateUserResponse>;
  getUser(id: number): Promise<User>;
  updateUser(id: number, data: Partial<User>): Promise<User>;
  deleteUser(id: number): Promise<void>;
}

Use in your code:

import { User, CreateUserRequest } from './types/api';

async function createUser(data: CreateUserRequest): Promise<User> {
  const response = await fetch('http://localhost:9000/api/v1/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data),
  });
  return response.json();
}

Generating React Query hooks

Export ready-to-use React Query hooks:

apicentric simulator export-query \
  --input services/users-api.yaml \
  --output src/hooks/useUsersApi.ts

Generated hooks:

src/hooks/useUsersApi.ts

// Generated by Apicentric
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

const API_BASE = 'http://localhost:9000/api/v1';

export interface User {
  id: number;
  name: string;
  email?: string;
}

export function useUsers() {
  return useQuery({
    queryKey: ['users'],
    queryFn: async () => {
      const response = await fetch(`${API_BASE}/users`);
      if (!response.ok) throw new Error('Failed to fetch users');
      return response.json() as Promise<User[]>;
    },
  });
}

export function useUser(id: number) {
  return useQuery({
    queryKey: ['users', id],
    queryFn: async () => {
      const response = await fetch(`${API_BASE}/users/${id}`);
      if (!response.ok) throw new Error('Failed to fetch user');
      return response.json() as Promise<User>;
    },
  });
}

export function useCreateUser() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: async (data: Omit<User, 'id'>) => {
      const response = await fetch(`${API_BASE}/users`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data),
      });
      if (!response.ok) throw new Error('Failed to create user');
      return response.json() as Promise<User>;
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['users'] });
    },
  });
}

export function useUpdateUser() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: async ({ id, data }: { id: number; data: Partial<User> }) => {
      const response = await fetch(`${API_BASE}/users/${id}`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data),
      });
      if (!response.ok) throw new Error('Failed to update user');
      return response.json() as Promise<User>;
    },
    onSuccess: (_, { id }) => {
      queryClient.invalidateQueries({ queryKey: ['users'] });
      queryClient.invalidateQueries({ queryKey: ['users', id] });
    },
  });
}

export function useDeleteUser() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: async (id: number) => {
      const response = await fetch(`${API_BASE}/users/${id}`, {
        method: 'DELETE',
      });
      if (!response.ok) throw new Error('Failed to delete user');
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['users'] });
    },
  });
}

Use in your React components:

import { useUsers, useCreateUser } from './hooks/useUsersApi';

function UsersPage() {
  const { data: users, isLoading, error } = useUsers();
  const createUser = useCreateUser();

  const handleCreate = () => {
    createUser.mutate({
      name: 'New User',
      email: '[email protected]',
    });
  };

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h1>Users</h1>
      <ul>
        {users?.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
      <button onClick={handleCreate}>Add User</button>
    </div>
  );
}

Generating React view components

Export complete React components:

apicentric simulator export-view \
  --input services/users-api.yaml \
  --output src/components/UsersView.tsx

Generated component:

src/components/UsersView.tsx

import React from 'react';
import { useUsers, useCreateUser, useDeleteUser } from '../hooks/useUsersApi';

export function UsersView() {
  const { data: users, isLoading, error } = useUsers();
  const createUser = useCreateUser();
  const deleteUser = useDeleteUser();
  const [formData, setFormData] = React.useState({ name: '', email: '' });

  if (isLoading) return <div className="loading">Loading users...</div>;
  if (error) return <div className="error">Error: {error.message}</div>;

  return (
    <div className="users-view">
      <h1>Users</h1>
      
      <form onSubmit={(e) => {
        e.preventDefault();
        createUser.mutate(formData);
        setFormData({ name: '', email: '' });
      }}>
        <input
          type="text"
          placeholder="Name"
          value={formData.name}
          onChange={(e) => setFormData({ ...formData, name: e.target.value })}
        />
        <input
          type="email"
          placeholder="Email"
          value={formData.email}
          onChange={(e) => setFormData({ ...formData, email: e.target.value })}
        />
        <button type="submit">Add User</button>
      </form>

      <ul className="users-list">
        {users?.map(user => (
          <li key={user.id}>
            <span>{user.name}</span>
            <span>{user.email}</span>
            <button onClick={() => deleteUser.mutate(user.id)}>Delete</button>
          </li>
        ))}
      </ul>
    </div>
  );
}

Batch exporting

Export multiple formats at once:

#!/bin/bash
# export-all.sh

SERVICE="services/users-api.yaml"

# OpenAPI spec
apicentric simulator export \
  --input "$SERVICE" \
  --output "docs/openapi.json" \
  --format openapi

# TypeScript types
apicentric simulator export-types \
  --input "$SERVICE" \
  --output "src/types/api.ts"

# React Query hooks
apicentric simulator export-query \
  --input "$SERVICE" \
  --output "src/hooks/useApi.ts"

# Postman collection
apicentric simulator export \
  --input "$SERVICE" \
  --output "postman/collection.json" \
  --format postman

echo "✅ All exports complete"

Run it:

chmod +x export-all.sh
./export-all.sh

CI/CD integration

GitHub Actions

Automate exports on every commit:

.github/workflows/export.yml

name: Export API Specs

on:
  push:
    paths:
      - 'services/**/*.yaml'

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Apicentric
        run: |
          curl -fsSL https://raw.githubusercontent.com/pmaojo/apicentric/main/scripts/install.sh | sh
      
      - name: Export OpenAPI
        run: |
          apicentric simulator export \
            --input services/api.yaml \
            --output docs/openapi.json \
            --format openapi
      
      - name: Export TypeScript
        run: |
          apicentric simulator export-types \
            --input services/api.yaml \
            --output src/types/api.ts
      
      - name: Commit generated files
        run: |
          git config user.name "GitHub Actions"
          git config user.email "[email protected]"
          git add docs/openapi.json src/types/api.ts
          git diff-index --quiet HEAD || git commit -m "chore: update generated API specs"
          git push

Troubleshooting

Missing types in export

Ensure your service has proper schema definitions:

endpoints:
  - method: POST
    path: /users
    request_body:
      content_type: application/json
      schema: |
        {
          "name": "string",
          "email": "string"
        }

Export fails with validation error

Validate your service first:

apicentric simulator validate --path services/api.yaml --verbose

Generated code has TypeScript errors

Check your response body formats are valid JSON:

# Bad - invalid JSON
body: '{id: 1, name: "Alice"}'

# Good - valid JSON
body: '{"id": 1, "name": "Alice"}'

Always validate exported OpenAPI specs using online validators like Swagger Editor before sharing them.

Next steps

Import specs

Import OpenAPI and Postman specs

Contract testing

Verify exports match real APIs

Request validation

Add validation to your services

Creating mocks

Learn about service definitions

Getting Started

Core Concepts

Features

Guides

Advanced

Troubleshooting

Exporting API specifications

Available export formats

Exporting to OpenAPI

What gets exported

Example export

Exporting to Postman

Generating TypeScript types

Generating React Query hooks

Generating React view components

Batch exporting

CI/CD integration

GitHub Actions

Troubleshooting

Missing types in export

Export fails with validation error

Generated code has TypeScript errors

Next steps

Import specs

Contract testing

Request validation

Creating mocks

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Features

Guides

Advanced

Troubleshooting

​Available export formats

​Exporting to OpenAPI

​What gets exported

​Example export

​Exporting to Postman

​Generating TypeScript types

​Generating React Query hooks

​Generating React view components

​Batch exporting

​CI/CD integration

​GitHub Actions

​Troubleshooting

​Missing types in export

​Export fails with validation error

​Generated code has TypeScript errors

​Next steps

Import specs

Contract testing

Request validation

Creating mocks

Build docs developers (and LLMs) love

Available export formats

Exporting to OpenAPI

What gets exported

Example export

Exporting to Postman

Generating TypeScript types

Generating React Query hooks

Generating React view components

Batch exporting

CI/CD integration

GitHub Actions

Troubleshooting

Missing types in export

Export fails with validation error

Generated code has TypeScript errors

Next steps