docs: OPA configuration ambiguous on policy configuration regarding dots v.s. slashes

[reinkrul]

Firstly, thanks for the OSS. It's the first FOSS API Gateway I found with out-of-the-box support for OAuth2 Token Introspection and OPA support (without it being behind an Enterprise-feature paywall).

Current State

The OPA plugin documentation (https://apisix.apache.org/docs/apisix/plugins/opa/) includes examples without policy namespace (example1, echo). If you have an OPA policy with a namespace (e.g. examples.echo), you have to configure this in APISIX as

{
"policy": "examples/echo"
}

(instead of examples.echo).

I only found this after spending a lot of digging through APISIX's OPA plugin code and OPA issues with similar characteristics. What doesn't help (aside from me being totally new to both APISIX and OPA), is that the log message is somewhat technocratic;

opa.lua:112: phase_func(): invalid OPA decision format: {"decision_id":"6d671f5e-baa6-43bf-bdb2-aec6116246b0"}
 err: `result` field does not exist, client: 192.168.65.1 (etc...)

Desired State

Document how policy should be configured with namespaces OPA packages ("use forward slashes"), and/or include an example with a namespace.

[shreemaan-abhishek]

Meanwhile you can take a look at the test cases to understand the usage better: https://github.com/apache/apisix/blob/master/t/plugin/opa.t https://github.com/apache/apisix/blob/master/t/plugin/opa2.t

[reinkrul]

@shreemaan-abhishek if I were to submit a PR, would you rather have a side note in the documentation on how to work with dots/slashes, or an example that uses it? Or both?

[shreemaan-abhishek]

i would prefer having a side note. wdyt @kayx23

[kayx23]

I prefer an example with description