Our great sponsors
-
postman-app-support
Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs—faster.
-
openapi-generator
OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)
-
SurveyJS
Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.
-
-
openapi-to-postman
Plugin for converting OpenAPI 3.0 specs to the Postman Collection (v2) format (by therockstorm)
-
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
This seems like a relatively normal use-case: update the OpenAPI spec and have all downstream artifacts ("Golden" Collection, Documentation, Forked Collections, API clients) automatically update to reflect those changes. If you'd like to see Postman handle this better, add your thoughts to this pull request.
Recent APIs I've built follow both the OpenAPI (formerly known as Swagger) and JSON:API specs. The former allows us to generate server-side data models and API clients in a number of languages using the OpenAPI Generator. The latter allows us to leverage shared conventions on how a RESTful JSON API should function.
They allow you to upload an OpenAPI schema and generate a collection from it, but not through their API. This means we can't automate it. So as a workaround, we use the openapi-to-postman tool to convert our schema to a Postman collection and then use their API to update the collection we provide our customers.
A big problem with this tool, however, is that it generates new IDs for endpoints each time you run it. This makes diffs hard to follow and, more importantly, breaks documentation URLs. To workaround that, we use a forked version that stores a sourcemap of the endpoints so the IDs remain stable.
Recent APIs I've built follow both the OpenAPI (formerly known as Swagger) and JSON:API specs. The former allows us to generate server-side data models and API clients in a number of languages using the OpenAPI Generator. The latter allows us to leverage shared conventions on how a RESTful JSON API should function.