|
| 1 | +--- |
| 2 | +title: <APIPage /> |
| 3 | +description: The component for rendering OpenAPI docs content |
| 4 | +--- |
| 5 | + |
| 6 | +## Overview |
| 7 | + |
| 8 | +Fumadocs OpenAPI uses a `<APIPage />` component to render page contents. |
| 9 | + |
| 10 | +When customising it, the options are split into server/client configs. |
| 11 | + |
| 12 | +```tsx tab="components/api-page.tsx" |
| 13 | +import { openapi } from '@/lib/openapi'; |
| 14 | +import { createAPIPage } from 'fumadocs-openapi/ui'; |
| 15 | +import client from './api-page.client'; |
| 16 | + |
| 17 | +export const APIPage = createAPIPage(openapi, { |
| 18 | + client, |
| 19 | + // server config |
| 20 | +}); |
| 21 | +``` |
| 22 | + |
| 23 | +```tsx tab="components/api-page.client.tsx" |
| 24 | +'use client'; |
| 25 | +import { defineClientConfig } from 'fumadocs-openapi/ui/client'; |
| 26 | + |
| 27 | +export default defineClientConfig({ |
| 28 | + // client config |
| 29 | +}); |
| 30 | +``` |
| 31 | + |
| 32 | +Installing the types packages is highly recommended for advanced customisations: |
| 33 | + |
| 34 | +```package-install |
| 35 | +openapi-types json-schema-typed -D |
| 36 | +``` |
| 37 | + |
| 38 | +It gives you a higher level of type-safety. |
| 39 | + |
| 40 | +### Generate Code Samples |
| 41 | + |
| 42 | +Generate custom code samples for each API endpoint. |
| 43 | + |
| 44 | +```ts |
| 45 | +import { openapi } from '@/lib/openapi'; |
| 46 | +import { createAPIPage } from 'fumadocs-openapi/ui'; |
| 47 | + |
| 48 | +export const APIPage = createAPIPage(openapi, { |
| 49 | + generateCodeSamples(endpoint) { |
| 50 | + return [ |
| 51 | + { |
| 52 | + id: 'js', |
| 53 | + lang: 'js', |
| 54 | + label: 'JavaScript SDK', |
| 55 | + source: "console.log('hello')", |
| 56 | + }, |
| 57 | + // or to disable the default code samples |
| 58 | + // set `source: false` |
| 59 | + { |
| 60 | + id: 'curl', |
| 61 | + lang: 'bash', |
| 62 | + source: false, |
| 63 | + }, |
| 64 | + ]; |
| 65 | + }, |
| 66 | +}); |
| 67 | +``` |
| 68 | + |
| 69 | +In addition, you can also specify code samples via OpenAPI schema. |
| 70 | + |
| 71 | +```yaml |
| 72 | +paths: |
| 73 | + /plants: |
| 74 | + get: |
| 75 | + x-codeSamples: |
| 76 | + - lang: js |
| 77 | + label: JavaScript SDK |
| 78 | + source: | |
| 79 | + const planter = require('planter'); |
| 80 | + planter.list({ unwatered: true }); |
| 81 | +``` |
| 82 | +
|
| 83 | +### References |
| 84 | +
|
| 85 | +<auto-type-table type=" |
| 86 | +export type { CreateAPIPageOptions } from 'fumadocs-openapi/ui' |
| 87 | +" name="CreateAPIPageOptions" /> |
| 88 | +
|
| 89 | +## Media Adapters |
| 90 | +
|
| 91 | +You can create a media adapter to support other media types in API pages, a media adapter implements: |
| 92 | +
|
| 93 | +- Converting value into `fetch()` body compatible with corresponding media type. |
| 94 | +- Generate code example based on different programming language/tool. |
| 95 | + |
| 96 | +Put your media adapters in a separate file. |
| 97 | + |
| 98 | +```ts title="lib/media-adapters.ts" twoslash |
| 99 | +import type { MediaAdapter } from 'fumadocs-openapi'; |
| 100 | +
|
| 101 | +export const mediaAdapters: Record<string, MediaAdapter> = { |
| 102 | + // example: custom `application/json |
| 103 | + 'application/json': { |
| 104 | + encode(data) { |
| 105 | + return JSON.stringify(data.body); |
| 106 | + }, |
| 107 | + // returns code that inits a `body` variable, used for request body |
| 108 | + generateExample(data, ctx) { |
| 109 | + if (ctx.lang === 'js') { |
| 110 | + return `const body = "hello world"`; |
| 111 | + } |
| 112 | + |
| 113 | + if (ctx.lang === 'python') { |
| 114 | + return `body = "hello world"`; |
| 115 | + } |
| 116 | + |
| 117 | + if (ctx.lang === 'go' && 'addImport' in ctx) { |
| 118 | + ctx.addImport('strings'); |
| 119 | + |
| 120 | + return `body := strings.NewReader("hello world")`; |
| 121 | + } |
| 122 | + }, |
| 123 | + }, |
| 124 | +}; |
| 125 | +``` |
| 126 | + |
| 127 | +Pass the adapter to both client & server configs. |
| 128 | + |
| 129 | +```tsx tab="components/api-page.tsx" |
| 130 | +import { openapi } from '@/lib/openapi'; |
| 131 | +import { createAPIPage } from 'fumadocs-openapi/ui'; |
| 132 | +import { mediaAdapters } from '@/lib/media-adapters'; |
| 133 | +import client from './api-page.client'; |
| 134 | + |
| 135 | +export const APIPage = createAPIPage(openapi, { |
| 136 | + client, |
| 137 | + // [!code ++] |
| 138 | + mediaAdapters, |
| 139 | +}); |
| 140 | +``` |
| 141 | + |
| 142 | +```tsx tab="components/api-page.client.tsx" |
| 143 | +'use client'; |
| 144 | +import { defineClientConfig } from 'fumadocs-openapi/ui/client'; |
| 145 | +import { mediaAdapters } from '@/lib/media-adapters'; |
| 146 | + |
| 147 | +export default defineClientConfig({ |
| 148 | + // [!code ++] |
| 149 | + mediaAdapters, |
| 150 | +}); |
| 151 | +``` |
0 commit comments