Generate and Check a Ferry API Markdown Reference
Admin ·
Start with a versioned API description and check that the essential parts of its contract reach the written reference. The ferry example contains one timetable read and one booking request with different authentication rules.
Document the timetable and booking operations
Load the example and convert with schemas and examples included. The status identifies OpenAPI 3.1.1, YAML input, two operations and one named schema. Timetables contains GET /departures/{pier}, and Bookings contains POST /bookings.
Find the required pier path parameter. The converter resolves its reference under components/parameters, and the optional window parameter belongs to the individual operation. The timetable declares anonymous access. The booking follows the API-wide BookingKey requirement and includes an application/json request with sailing 08:10.
Fit the reference into an existing README
Set Top heading level to H2, then clear Include examples and Include schemas. Convert again. The file begins with an H2 for the API title, and the 200 response keeps its schema reference without the named schema section or example payload.
Descriptions in the export appear as literal text. Review any link or formatting that you want to restore in your documentation system before publishing the file.
Review reference notices before sharing the Markdown
Return to the full example and change the reference to the Pier parameter to ./common.yaml#/components/parameters/Pier. Convert again. The reference remains visible with a notice about its external location. Bundle those definitions into the input spec to include their documented values.
Swagger 2.0 uses definitions and securityDefinitions. Check consumes and produces alongside operation parameters and responses when comparing Markdown from a legacy description.
OpenAPI Specification 3.2.1 operations and referencesSwagger 2.0 specification
Common questions
Why must I quote numeric response keys in YAML?
The API description has string property names. Use a quoted response key such as '200' so it stays a string in the JSON representation.
Where do webhook operations appear?
Top-level OpenAPI webhooks are grouped with operations by tag and marked as webhooks. Review their names and response details in the export.