Best Practice/OpenAPI Design question: Supporting internal and external APIs.
My goal is to develop and API layer on top of on-premise data sources in Azure. The APIs serve two business use cases, a new Azure hosted Portal and Client APIs. Clients can perform all the actions in the Portal using the APIs.
TL;DR I have hundreds of EJBs running on premise. I want to use the EJB clients to provide data for the APIs. The EJBs and APIs run as an App Service. API Management service is used to expose the APIs to both the portal and clients.
I would like to design the APIs for both use cases using one OpenAPI spec. Response/Request objects for the Portal include internal indexes and helper information that I don't want to expose in the Client APIs. Because I can add tags at the API management layer I can identify if the call originates from the Portal or Client API. The code calling the EJB clients can see whether the caller is the Portal or a Client and return the correct response object.
Can I solve this by declaring multiple response objects and use the oneOf keyword creating a complex type? This seems like it would make the auto generated documentation confusing. Unless the set of internal objects can be block from doc generation.
The other option is two OpenAPI specs and double the code.