server.oas.enabled: true

curl -s -uelastic:changeme http://localhost:5601/api/oas\?pathStartsWith\=/api/foo

// In server/schemas/v1.ts
import { schema, TypeOf } from '@kbn/config-schema';

export const fooResource = schema.object({
  name: schema.string({
    meta: { description: 'A unique identifier for...' },
  }),
  // ...and any other fields you may need
});

export type FooResource = TypeOf<typeof fooResource>;

// In common/foo/v1.ts
export type { FooResource } from '../server/schemas/v1';

// In common/index.ts expose this as the "latest" schema shape
export type { FooResource } from './latest';

export * as fooResourceV1 from '../foo/v1';

// Somewhere in your plugin's server/routes folder
import { schema, TypeOf } from '@kbn/config-schema';
import type { FooResource } from '../../../common';
import { fooResource } from '../../schemas/v1';

// Note: this response schema is instantiated lazily to avoid creating schemas that are not needed in most cases!
const fooResourceResponse = () => {
  return schema.object({
    id: schema.string({
      maxLength: 20,
      meta: { description: 'Add a description.' }
    }),
    name: schema.string({ meta: { description: 'Add a description.' } }),
    createdAt: schema.string({
      meta: {
        description: 'Add a description.',
        deprecated: true,  // An indicator that the property is deprecated
      },
    }),
  })
}

// Note: TypeOf can extract types for lazily instantiated schemas
type FooResourceResponse = TypeOf<typeof fooResourceResponse>

function registerFooRoute(router: IRouter, docLinks: DoclinksStart) {
  router.versioned
    .post({
      path: '/api/foo',
      access: 'public',
      summary: 'Create a foo resource'
      description: `A foo resource enables baz. See the following [documentation](${docLinks.links.fooResource}).`,
      deprecated: true,  // An indicator that the operation is deprecated
      options: {
        tags: ['oas-tag:my tag'],  // Each operation must have a tag that's used to group similar endpoints in the docs
        availability: {
          since: '1.0.0', // The version that the API was added.
          stability: 'experimental', // The current lifecycle: experimental, beta, or stable
        },
      },
    })
    .addVersion({
      version: '2023-10-31',
      validate: {
        request: {
          body: fooResource,
        },
        response: {
          200: {
            description: 'Indicates a successful call.',
            body: fooResourceResponse,
          },
        },
      },
    },
    async (ctx, req, res) => {
      const core = await ctx.core;
      const savedObjectsClient = core.savedObjects.client;
      const body = req.body;
      const foo = await createFoo({ name: body.name });
      // This is our HTTP translation layer to ensure only the necessary fields included
      const responseBody: FooResourceResponse = {
        id: foo.id,
        name: foo.name,
        createdAt: foo.createdAt,
      };
      return res.ok({ body: responseBody });
    }
  );
}

// ...
    .addVersion({
      version: '2023-10-31',
      options: {
        // Be sure and lazily instantiate this value. It's only used at dev time!
        oasOperationObject: () => ({
          requestBody: {
            content: {
              'application/json': {
                examples: {
                  fooExample1: {
                    summary: 'An example foo request',
                    value: {
                      name: 'Cool foo!',
                    } as FooResource,
                  },
                },
              },
            },
          },
          responses: {
            200: {
              content: {
                'application/json': {
                  examples: {
                    /* Put your 200 response examples here */
                  },
                },
              },
            },
          },
        }),
      },
      validate: {
        request: {
          body: fooResource,
        },
        response: {
          200: {
            body: fooResourceResponse,
          },
        },
      },
    },
// ...

import path from 'node:path';

const oasOperationObject: () => path.join(__dirname, 'foo.examples.yaml'),

// ...
    .addVersion({
      version: '2023-10-31',
      options: {
        oasOperationObject,
      },
      validate: {
        request: {
          body: fooResource,
        },
        response: {
          200: {
            body: fooResourceResponse,
          },
        },
      },
    },
// ...

requestBody:
  content:
    application/json:
      examples: # Make sure to use the examples array, example (singular) has been deprecated
        fooExample:
          summary: Foo example
          description: >
            An example request of creating foo.
          value:
            name: 'Cool foo!'
        fooExampleRef:
          # You can use JSONSchema $refs to organize this file further
          $ref: "./examples/foo_example_i_factored_out_of_this_file.yaml"
responses:
  200:
    content:
      application/json:
        examples:
          # Apply a similar pattern to writing examples here
x-codeSamples:
- lang: cURL
  # label: A label which will be used as a title. Defaults to the lang value.
  source: |
    curl \
      -X POST /api/foo
      -H "kbn-xsrf: true"
      -d '{...}'
- lang: Console
  source: |
    POST kbn:/api/agent_builder/tools
    {...}

const fooResourceResponse = () => {
  return schema.object({
    id: schema.string({ maxLength: 20, meta: { description: 'An unique ID for a foo resource.'} }),
    name: schema.string({ meta: { description: 'A human friendly name for a foo resource.'} }),
    createdAt: schema.string({ meta: { description: 'The ISO date a foo resource was created.'} }),
  })
}

// @kbn/config-schema
schema.string({
  meta: {
    description: 'Add a description.',
    availability: { stability: 'stable', since: '9.4.0' },
  },
});

// @kbn/zod/v4
import { z } from '@kbn/zod/v4';

z.string().meta({
  openapi: {
    availability: { stability: 'stable', since: '9.4.0' },
  },
});