Explain the execution flow of API documentation generation in a CI/CD pipeline using Swagger/OpenAPI tooling?

A mature CI/CD pipeline treats the OpenAPI document as a build artifact in its own right, validating, testing, and publishing it alongside the application code rather than as a manual, disconnected side task someone remembers to do occasionally.

The pipeline typically branches early depending on whether the team writes the spec by hand or generates it from code annotations (like springdoc-openapi): hand-written specs get linted for structural and style correctness, while annotation-generated ones are extracted from a built application artifact first, since there's no static file to lint until the code compiles.

From there, both paths converge on the same downstream steps: contract tests confirm the live API's actual behavior matches the spec, and only after every check passes does the pipeline publish updated documentation and, optionally, regenerate and publish client SDKs — ensuring that anything reaching consumers, whether it's a documentation page or a generated library, has already been verified against the real, currently-deployed API rather than being generated from a stale or inconsistent source.