Configuration file

This project is requires a configuration file.
You need to create a configuration file named as api-codegen.config.{ts|js|mjs|json}. Recommends to create api-codegen.config.ts or you can create a configuration file with your own name, but you need to use -c, --config option in cli.

use defineConfig function

This function is exports from mobx-tanstack-query-api/cli import. It adds typings for your configuration file.

import { defineConfig } from "mobx-tanstack-query-api/cli";
import path from "path";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default defineConfig({
  input: 'path-or-url-to-openapi.{yaml|json}' | object,
  output: 'path-to-output-directory',
})

Multiple configs

You can pass multiple configs to defineConfig function

import { defineConfig } from "mobx-tanstack-query-api/cli";
import path from "path";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default defineConfig([
  {
    input: 'path-or-url-to-openapi.{yaml|json}' | object,
    output: 'path-to-output-directory',
  },
  {
    input: 'path-or-url-to-openapi.{yaml|json}' | object,
    output: 'path-to-output-directory',
  },
  {
    input: 'path-or-url-to-openapi.{yaml|json}' | object,
    output: 'path-to-output-directory',
  }
])

Options

input

Required input path or url to OpenAPI/Swagger file or OpenAPI/Swagger object.
Sometimes will be helpful to use fetchSchemaRequestOptions to fetch OpenAPI/Swagger file with some custom request options (like auth headers).

input: 'https://gitlab.com/api/v4/openapi.json'

output

Required output directory path.

fetchSchemaRequestOptions

Optional fetch options to fetch OpenAPI/Swagger file.
Using this option you can add auth headers, etc.
Example:

fetchSchemaRequestOptions: {
  headers: {
    'PRIVATE-TOKEN': `GitlabToken`,
    'Authorization': `Basic ${Buffer.from('js2me:qwerty').toString('base64')}`,
  }
}

httpClient

This is import property configuration for all your generated endpoints.
Default value: 'builtin' which means use built-in http client.
You can override it to use your own http client.

Sometime this is useful if you need to customize fetch api behavior or add your own initialization for HttpClient.

Example:

Create your own file with http client:

src/shared/api/http-client.ts

import { HttpClient } from 'mobx-tanstack-query-api';

export const myExportHttpClientName = new HttpClient({
  baseUrl: 'https://mydomainforapi.com',
})

src/api-codegen.config.ts

httpClient: {
  exportName: 'myExportHttpClientName',
  path: '@/shared/api/http-client',
}

So you will in generated endpoint files this code lines:

src/shared/api/__generated__

import { myExportHttpClientName } from "@/shared/api/http-client";
import {
  Endpoint,
  HttpResponse,
  RequestParams,
} from "mobx-tanstack-query-api";
...
export const getMyData = new Endpoint<
  HttpResponse<GetMyDataDC, GetMyDataError>,
  GetMyDataParams,
  any
>(
  {
    params: ({ query, requestParams }) => ({
      path: `/api/v1/get-my-data`,
      method: "GET",
      query: query,
      ...requestParams,
    }),
    requiredParams: [],
    operationId: "getMyData",
    path: ["api", "v1", "get-my-data"],
    tags: [Tag.MyData],
    meta: {} as any,
  },
  queryClient,
  myExportHttpClientName,
);

queryClient

Same as httpClient but for queryClient.

This is import property configuration for all your generated endpoints.
Default value: 'builtin' which means use built-in Tanstack's query client.
You can override it to use your own query client.

Sometime this is useful if you need to add configuration for EndpointQueryClient

Example:

Create your own file with query client:

src/shared/api/query-client.ts

import { EndpointQueryClient } from 'mobx-tanstack-query-api';

export const myQueryClient = new EndpointQueryClient({
  defaultOptions: {
    queries: {
      enableOnDemand: true,
      throwOnError: true,
      refetchOnWindowFocus: false,
      refetchOnReconnect: false,
      staleTime: 0,
      retry: false,
    },
    mutations: {
      throwOnError: true,
    },
  },
})

src/api-codegen.config.ts

queryClient: {
  exportName: 'myQueryClient',
  path: '@/shared/api/query-client',
}

So you will in generated endpoint files this code lines:

src/shared/api/__generated__

import { myQueryClient } from "@/shared/api/query-client";
import {
  Endpoint,
  HttpResponse,
  RequestParams,
} from "mobx-tanstack-query-api";
...
export const getMyData = new Endpoint<
  HttpResponse<GetMyDataDC, GetMyDataError>,
  GetMyDataParams,
  any
>(
  {
    params: ({ query, requestParams }) => ({
      path: `/api/v1/get-my-data`,
      method: "GET",
      query: query,
      ...requestParams,
    }),
    requiredParams: [],
    operationId: "getMyData",
    path: ["api", "v1", "get-my-data"],
    tags: [Tag.MyData],
    meta: {} as any,
  },
  myQueryClient,
  httpClient,
);

endpoint

Same as queryClient, httpClient but for Endpoint.

import { MyEndpoint } from "@/shared/api/my-endpoint";
...
export const getMyData = new MyEndpoint<
...

filterEndpoints

This option is needed to filter endpoints.
You can pass string or array of strings or regular expression which will be comparing with Endpoint.operationId.
Also you can pass function to manual filter endpoints.

Example:

filterEndpoints: (endpoint) => 
  endpoint.raw.operationId !== 'getMyData' &&
  !endpont.raw.route.startsWith('/my/another/data')

addPathSegmentToRouteName

This option is needed to add path segment to route name.
Default: false
Examples:

// operationId: 'getById'
// path: '/api/v1/users/1'
addPathSegmentToRouteName: true, // means add 0 (api) path segment

output will be:

export const apiGetById = new Endpoint<...>
// [api][getById]

// operationId: 'getById'
// path: '/api/v1/users/1'
addPathSegmentToRouteName: 1, // means add 1 (v1) path segment

output will be:

export const v1GetById = new Endpoint<...>
// [v1][getById]

If you need to format route name better to use formatEndpointName

otherCodegenParams

Other codegen params for swagger-typescript-api codegen.
See swagger-typescript-api for more info.

filterGroups

This option is needed to filter endpoint groups.
You can pass string or array of strings or regular expression which will be comparing with group name.
Also you can pass function to manual filter endpoint groups.

namespace

Collect all exports into single namespace.
Can be helpful if you work with multiple backends.

Example: without namespace:

export * from "./endpoints";
export * from "./data-contracts";

with namespace:

export * as namespaceName from "./__exports"; // exports like above

namespaceName.login.toMutation()

Example:

namespace: 'api'

requestPathPrefix

This option is allow to add path prefix to endpoint request path

Example:

requestPathPrefix: '/__super_api_prefix'

export const getMyData = new Endpoint<...>(
  {
    params: ({ query, requestParams }) => ({
      path: `/__super_api_prefix/api/v1/get-my-data`,
      method: "GET",
      query: query,
      ...requestParams,
    }),
    requiredParams: [],
    operationId: "getMyData",
    path: ["__super_api_prefix", "api", "v1", "get-my-data"],
    tags: [Tag.MyData],
    meta: {} as any,
  },
  myQueryClient,
  httpClient,
);

requestPathSuffix

This option is allow to add path suffix to endpoint request path

Example:

requestPathSuffix: '/__super_api_fx'

export const getMyData = new Endpoint<...>(
  {
    params: ({ query, requestParams }) => ({
      path: `/api/v1/get-my-data/__super_api_fx`,
      method: "GET",
      query: query,
      ...requestParams,
    }),
    requiredParams: [],
    operationId: "getMyData",
    path: ["api", "v1", "get-my-data", "__super_api_fx"],
    tags: [Tag.MyData],
    meta: {} as any,
  },
  myQueryClient,
  httpClient,
);

removeUnusedTypes

This option is removes all data contracts which are not used in any endpoint.
Default: false

This is slow operation

Example:

removeUnusedTypes: true
// or 
removeUnusedTypes: {
  keepTypes: ['MySuperType']
}

formatEndpointName

This option is allow to format endpoint name.

Example:

formatEndpointName: (endpointName, endpointData) => {
  return `${endpointName}Endpoint`;
}
// `getMyData` -> `getMyDataEndpoint`

groupBy

This option is allow to group endpoints into object.
Default: false

You can group endpoints by:

• tag - endpoint tag (first tag)
• tag-{number} - specific endpoint tag index number
• path-segment - endpoint path segment (first path segment)
• path-segment-{number} - specific endpoint path segment index number
• custom behavior with function

Example:

groupBy: 'tag'

groupBy: endpoint =>
  endpoint.raw.route.includes('users') ? 'users' : 'other'

groupBy: endpoint => {
  if (endpoint.raw && 'x-ogen-operation-group' in endpoint.raw) {
    return endpoint.raw['x-ogen-operation-group'];
  }

  return endpoint.tags?.[0] ?? 'other';
}

formatExportGroupName

This option is allow to format endpoints group export name.

Example:

formatExportGroupName: (groupName) => {
  return `${groupName}Api`;
}

outputType

This option is allow to choose output type.
Default: one-endpoint-per-file

Variants:

• one-endpoint-per-file - one file per endpoint

Example with groups:

* outputdir
*  groupname
*    index.ts
*    endpoints
*      index.ts
*      get-endpoint-1.ts
*      get-endpoint-n.ts

Example without groups:

* outputdir
*  index.ts
*  endpoints
*    index.ts
*    get-endpoint-1.ts
*    get-endpoint-n.ts

• endpoints-per-file - all endpoints in one file Example with groups:

* outputdir
*  groupname
*    index.ts
*    endpoints.ts

Example without groups:

* outputdir
*  index.ts
*  endpoints.ts

getRequestMeta

This option is allow to add some meta information for endpoint request.
Can be helpful if you need customize base url for http request.

Example:

getRequestMeta: () => ({
  tmplData: `{ service: 'auth' }`,
}),

export const getFruits = new Endpoint<
  HttpResponse<GetFruitsDataDC, GetRolesErrorDC>,
  GetFruitsParams,
  any
>(
  {
    params: ({ query, requestParams }) => ({
      path: `/fruits`,
      method: "GET",
      meta: { service: 'auth' },
      query: query,
      secure: true,
      ...requestParams,
    }),
  },
  ...
  queryClient,
  httpClient,
);

getEndpointMeta

This option is allow to add some meta information for endpoint.

Example:

Example:

getEndpointMeta: () => ({
  typeName: `{ somedata: string }`,
  tmplData: `{ somedata: '123' }`,
}),

export const getFruits = new Endpoint<
  HttpResponse<GetFruitsDataDC, GetRolesErrorDC>,
  GetFruitsParams,
  { somedata: string }
>(
  {
    params: ({ query, requestParams }) => ({
      path: `/fruits`,
      method: "GET",
      query: query,
      secure: true,
      ...requestParams,
    }),
    operationId: "getFruits",
    path: ["fruits"],
    tags: [Tag.Frutis],
    meta: { somedata: '123' },
  },
  ...
  queryClient,
  httpClient,
);


getFruits.meta.somedata; // '123'