Is there an easy way to denote internal and external endpoints, and a way to generate internal or external swagger docs?

[prodikl]

So far this library has been a huge help to our organization.

I wanted to mark endpoints internal or external, then when I build the documentation, ideally I could pass in a parameter "internal" or "external."

This way, we could hide away endpoints that are just for internal use.

I was going to fork and add my own annotation (e.g. @swg\Environment or just @swg\Internal / External) but I wanted to ask first if there was a way to do this already!

Thanks

[bfanger]

This not build-in, keep me posted on your progress, I think it would be a nice add-on for the related projects page.

[babarizbak]

@prodikl I was just searching for this too, since I will soon have to maintain both internal and external API docs from the same basecode. I would be very interested to hear from you if you make any progress on this.

@bfanger Wouldn't it be nice to have this in the core of swagger-php? Or is there any other way to do it in the current version?

Thanks,

[bfanger]

In the current version you can use a custom properties For example: x-internal=true and x-external=true

The output swagger-php generates will contain all documentation, but it's just json, so splitting it into 2 json files should be trivial for a php developer 😉

[prodikl]

@babarizbak unfortunately my company didn't want me to devote time to this issue and instead we're generating normally and chopping down by hand for limited external docs.

i'd still consider adding something like this in my personal time but i think as a community we'd need to decide what the steps should look like

• environment var per endpoint kind of like tags?
• then maybe add a cli switch like ./vendor/bin/swagger src -o public/docs/swagger --environment internal or something?

[annatech]

@prodikl I ran across the same issue regarding selective publishing of Swagger Docs. What I ended up doing was building additional functionality into my commercial product (https://getcapi.org) which leverages the CMS's group ACL to selectively render the swagger json which feeds into the Swagger UI.

This all works, however, because I build REST APIs endpoint collections as CMS plugins. These plugins occupy known directory paths. Within my code, I am able to look up ACL configuration, map it against the user making the request and in real-time generate the Swagger json based on the allowed paths for the zircote Doctrine processor (done via a foreach loop which builds the director paths array).

Without such pre-processing of the Swagger json generation, you would need to modify the source code for Swagger UI to do such things as:

• Allow tags assignment per environment. OpenAPI 3.0 allows for multiple environments. Tags assigned to such environments could, in theory, but cross-referenced against tags associated with specific routes, thereby providing the option to automatically selectively control Swagger UI rendering.
• This isn't really a "secure" solution though because anyone can just get your full swagger json path.

I'm not sure it would be a good idea to customize zircote/swagger-php to follow such custom rule sets for Doctrine parsing. From my experience, it seems to provide enough functionality to allow the end user to choose which directory paths to pass to the parser class.

[babarizbak]

@bfanger OK, it may be not that hard to use custom properties and then parse the JSON file, but it still needs some hand-writing-glue-code.

@prodikl I agree with your proposal:

1. Adding a new field which could be set for each endpoint (let's call it "environment"), containing an array of possible values;
2. Adding a new option to the bin/swagger command, allowing to filter by "environment".

Clean and easy.

[bfanger]

What is, and is not part of an environment (or api-version) could be as simple as filtering based on 'v1' vs 'v2' in the path.
But the differences in an api can be much more complex/nuanced. I think @babarizbak proposed solution is too simple.

I've decided that filtering the generated documentation is outside of the scope of the swagger-php project.

It can be done, but requires insight into your api and building your own filtering logic like @annatech has done, is the recommended solution.