An OpenAPI library is a separate OpenAPI document containing reusable components for multiple APIs. It centralizes shared schemas, parameters, headers, and responses, improving consistency, interoperability, and maintainability. section 17.1 section 17.6
A library can provide:
- Reusable schemas such as Errors. section 17.6.1
- Common parameters such as Pagination. section 17.6.1
- Shared headers and responses such as ResourceLocation and ResourceNotFound. section 17.6.1
- Standard responses or request headers enforced through Spectral rules. section 18.4.3 section 18.6.4
Referencing shared pagination
A Shopping API can reuse a Pagination parameter from shared-components.yaml with a reference such as /path/to/shared-components.yaml#/components/parameters/Pagination. Relative references resolve from the location of the referring OpenAPI file. section 17.6.2
Listing 17.18 Creating an OpenAPI library
openapi: 3.1.0
info:
title: Shared components
version: "1.0" #1
#2
components: #3
schemas:
Errors: ...
parameters:
Pagination: ...
headers:
ResourceLocation: ...
responses:
ResourceNotFound: ...
The component listing shows the minimal shape of an OpenAPI 3.1 library: independent metadata plus a components block, without paths or webhooks. section 17.6.1
