Example Overlays
Overlays act as a layer on top of your existing OpenAPI specification, allowing you to apply modifications and extensions seamlessly. They are perfect for adding new features, customizing responses, and adapting specifications to specific needs without disrupting the underlying structure.
To demonstrate the power of overlays, we’ll use a sample OpenAPI Specification for “The Speakeasy Bar.” This initial spec sets the stage for our overlay examples:
openapi: 3.1.0info:title: The Speakeasy Barversion: 1.0.0summary: A bar that serves drinks.servers:- url: https://speakeasy.bardescription: The production server.security:- apiKey: []tags:- name: drinksdescription: The drinks endpoints.- name: ordersdescription: The orders endpoints.paths:/dinner/:post:...get:.../drinks/:post:...
Let’s explore how overlays can enhance and adapt this specification to do the following:
- Adding Speakeasy Extensions
- Adding SDK Specific Documentation
- Modifying Auto-Generated Schemas
- Adding Examples to API Documentation
- Hiding Internal APIs from a Public SDK
- Removing specific PUT operation
- Standardize Configurations
Adding Speakeasy Extensions
Objective: Integrate Terraform functionality into the API specification for order management.
Overlay Action:
overlay: 1.0.0info:title: Add Terraform Functionality to Order Schemaversion: 1.1.0actions:- target: "$.components.schemas.Order"update:- x-speakeasy-entity: Orderdescription: "Enables Terraform provider support for the Order schema."
Adding SDK Specific Documentation
Objective: Provide tailored instructions for Java and JavaScript SDKs for the /orders
endpoint.
Overlay Action:
overlay: 1.0.0info:title: Distinguish Order Endpoint Docs for Java and JavaScript SDKsversion: 1.1.1actions:- target: "$.paths['/orders'].post.description"update:- value: "For Java SDK: use `OrderService.placeOrder()`. For JavaScript SDK: use `orderService.placeOrder()`."
Modifying Auto-Generated Schemas
Objective: Enhance the precision of the Drink schema, making it more descriptive and informative for API consumers.
overlay: 1.0.0info:title: Refine Drink Schema for Better Clarityversion: 1.1.2actions:- target: "$.components.schemas.Drink"update:- properties:type:type: stringdescription: "Type of drink, e.g., 'cocktail', 'beer'."alcoholContent:type: numberdescription: "Percentage of alcohol by volume."
Adding Examples to API Documentation
Objective: Illustrate the drink ordering process with a practical example for user clarity.
overlay: 1.0.0info:title: Add Drink Order Example for User Clarityversion: 1.1.3actions:- target: "$.paths['/drinks/order'].post"update:- examples:standardOrder:summary: "Standard order example"value:drink: "Old Fashioned"quantity: 1
Hiding Internal APIs from a Public SDK
Objective: Restrict the visibility of internal staff management endpoints.
overlay: 1.0.0info:title: Secure Internal Staff Management Endpointversion: 1.1.4actions:- target: "$.paths['/internal/staff']"update:- x-internal: truedescription: "This endpoint is restricted for internal staff management and not visible in public SDKs."
Removing Specific Put Operation
Objective: Exclude PUT operations without the x-speakeasy-entity-operation.
Overlay Action:
overlay: 1.0.0info:title: Remove Non-Essential PUT Operationsversion: 1.1.0actions:- target: $.paths.*.put[?(! @.x-speakeasy-entity-operation)]remove: true
Standardize Configurations
Objective: Remove the server and security configurations from each operation within the paths.
Overlay Action:
overlay: 1.0.0info:title: Standardize Server and Security Configurationsversion: 1.1.0actions:- target: $.paths.*.*.serversremove: true- target: $.paths.*.*.securityremove: true