An API artifact is an API definition file or a product derived from one, such as reference documentation, a client SDK, an alternative definition format, or an API score report. Generating these through a CI/CD pipeline gives teams a repeatable alternative to manual, ad hoc production. Source-stage checks provide design feedback; later stages prepare approved definitions for consumers and publication. section 8.0 section 9.0
A build-stage workflow can prepare a definition for a particular audience:
- Bundle a multifile definition into one file, then filter or rewrite it to produce the intended view. section 9.1
- Sort fields consistently, remove unused components, or create a Postman collection from an OpenAPI file. section 9.1
- Upload the processed definition to an artifact store so later pipeline steps can retrieve it or publish it through a developer portal. section 9.1
Internal and external views
Suppose one OpenAPI definition contains both internal- and external-facing endpoints. Mark internal objects with x-internal:true, then filter them out when generating the external artifact. The published view can also replace an internal server URL with an external sandbox URL. Automating those transformations keeps the two views distinct without relying on manual edits. section 9.1
Table 9.1 Summary of the generated API definition artifact
|
Type of artifact
|
Users of the artifact
|
What do they need the artifact for?
|
Source files the artifact is generated from
|
Tool to generate the artifact
|
Where artifact will be stored
|
|---|---|---|---|---|---|
|
Processed OpenAPI definition
|
• External API consumers
• Developer portal
• Later stages of the continuous integration/continuous delivery (CI/CD) pipeline
|
• Shared with external API consumers
• Used for generating the API reference in the developer portal
• Used to generate SDKs
|
Multifile API definitions
|
Redocly CLI, openapi- format, openapi- filter
|
Apicurio API registry
|
The artifact summary traces a processed OpenAPI definition from multifile source files through generation tools to an API registry, and identifies its consumers and downstream uses. section 9.1
