Creating public and private Open API documentation from yaml file - yaml

Question

I have an OpenAPI document to describe some Endpoints. Some of those endpoints shall be public (visible for final users) and other private (visible to dev team only).
I'd like to know if is there a way to create only 1 yaml file containing all api methods and generate 2 docs page (1 for public endpoints and other for private). Is there a flag or configuration that would allow me to differ the endpoint type and make it visible or hidden?
I also need to do that on request level. There are some endpoints in which the request body has some "private" attributes (that final user shouldn't be aware of). Assuming that the first statement is true (there is a way I can create 2 api docs from a single YAML file), would it be possible to hide some request model attributes when applying the public alias documentation?

Answer 1

For those who are in doubt of how can this be accomplished, that's how I did:
I created a set of private keywords that are transparent for OpenApi (they are common strings)
I also created a python script that navigates through the yaml file and every time it finds one of these private keywords, it removes the yaml node it is contained.
Q: How did I manage to do that for endpoints?
A: I created in the "tags" section one called Private and all the private endpoints must refer to it. That's how I remove the private endpoints.
Q: How did I manage to do that for attributes?
A: In the attribute (or any element I want to make private) "description" tag, I add the keyword "Private". So if my script finds inside the description this string, the element is removed.
Of course that for the private OpenApi yaml file I create these tags I am using to generate the public version are still there. But since they are only strings, that's no big deal.
To navigate by the yaml file I used the following python lib: ruamel
So I keep recursively navigating through the file searching for OpenApi operations which the tag is called "Private" or the attributes which the description tag contains the char sequence "Private"

Answer 2

Instanciate a same OpenAPI file for several use context is a common need.
The classical solution is to copy-paste your files but in term of maintenability is not great!
Because I had the same need, I wrote my own tool "OpenAPI Dev Tool" (see github).
With this tool, you can design just one API and instanciate it for several contexts (private / public for example) without duplicate any lines or files (it uses EJS template engine).
For example, you can define a configuration file like that :
{
"folder": "./specs",
"specs": [
{
"file": "/petstore.yaml",
"context": {
private: true
}
},
{
"file": "/petstore.yaml"
"context": {
private: false
}
}
]
}
Where the same YAML file is specified but for 2 different contexts (public / private).
And in your petstore.yaml, you can have :
openapi: 3.0.0
...
components:
<%if (public) { %>
securitySchemes:
basicAuth:
type: http
scheme: basic
<% } %>
...
<%if (public) { %>
security:
- basicAuth: []
<% } %>
...
And the end, 2 specs will be produced from a same YAML file but for these 2 contexts :)