Hello community
I have a general question about how OpenAPI definitions are managed in an organization; And wondering if this community may have any ideas regarding best practices.
At my company we have begun to implement the Developer Portal on Apigee Edge for Public Cloud.
We house a diverse portfolio of applications with APIs shared internally and externally with our customers as well as other ISVs and partner groups.
I’m a fairly new member of our API management team, and am looking into best practices for managing the lifecycle of the APIs, and the OpenAPI contracts.
As it stands now, we have built out our Developer Portal to publish our internal and external OpenAPI definitions to various groups - using the Apigee Audiences feature to share with:
- internal developers
- external partners, customers, and ISVs
In the past, the various api contracts have been passed around as:
- PDF documents (for legacy apps)
- Swagger links (for internal devs) auto-generated by annotation analysis libs (like Springdoc)
- OpenAPI defs (json/yaml) (also auto-generated by annotation)
But to date, there hasn’t been any process or controllership around how this is managed - which is where the Dev Portal comes in.
My question for other teams is, how do you manage the flow of OpenAPI contracts through your organization?
For us it’s currently a manual process. Using an API based on Java controllers as an example:
- As API is developed/updated, Springdoc annotation library automatically generates OpenAPI def and swagger link
- The Springdoc annotation library is configured to target various endpoints for different groups (internal, external, etc), resulting in multiple scoped definitions of OpenAPI contract
- Developer shares updated OpenAPI definitions (json/yaml) with API management team, to be shared in Developer Portal
- API management team uploads the json/yaml to Apigee Edge
- API management team refreshes the “spec snapshot” in the Dev Portal Catalog admin interface
However, this is a lot of manual touchpoints, and as our portfolio proliferates, a lot of operational resource overhead and potential for error.
I am in the process of investigating a middle automation layer - An automated process, that would periodically scan an application’s exposed json/yaml definition, and then automatically push it (via Apigee mgmt api) to the dev portal.
What are other teams doing in this area?
Kind regards from upstate Vermont 