Hi All,
I have a question about OpenAPI Specification management (I'm going to call it swagger because it is easier to type).
I will use the Petstore example for my discussion as people are familiar with it - http://petstore.swagger.io/#/.
If we think about how the majority of people working on an API Program start out, they will create a set of APIs they want to expose.
In Petstore, we have 3 APIs and a total of 20 resources:
- Pet (8 resources)
- Store (4 resources)
- User (8 resources)
Now I consider Petstore to be an "API Product", and as such, I think it could be reasonable to consider we are only seeing a fraction of the actual resources available for that API.
- Pet (8 resources / 14 resources in total)
- Store (4 resources / 10 resources in total)
- User (8 resources / 20 resources in total)
My questions are these:
1 - Is it reasonable to have a swagger each of my APIs and Resources (internal catalogue) and for my API Products (external catalogue of select APIs and Resources)?
In this case, the internal catalogue would be a swagger for each of my 3 APIs with 14, 10 and 20 resources respectively, and external catalogue as per PetStore - or 1 swagger containing 3 apis and 20 resources.
2 - How would one manage the overhead of this, and the potential myriad of combinations?
3 - How would a client manage the discoverability of this across a company that could have multiple federated teams and business units potentially across the world?
4 - What are some other pain points for large companies with hundreds or thousands of resources to be created, discovered, "productised", versioned and managed?
5 - Do you create a swagger for each of your environments (Dev, Integration Test, User Test, Performacne Test, Production)?
User | Count |
---|---|
7 | |
2 | |
2 | |
1 | |
1 |