Clarification meaning of {{API_NAME}}.{{SPECIFIC_CODE}}

[PedroDiez]

What type of PR is this?

• documentation

What this PR does / why we need it:

This PR deals with some clarification required in order to state clearly how to define an specific API exception under the {{API_NAME}}.{{SPECIFIC_CODE}} scheme

Which issue(s) this PR fixes:

Fixes #538

Does this PR introduce a breaking change?

• Yes
• No

Special notes for reviewers:

N/A

Changelog input

  Clarification meaning of {{API_NAME}}.{{SPECIFIC_CODE}}

Additional documentation

N/A

[patrice-conil]

LGTM

[tlohmar]

Looks good.

[rartych]

In CAMARA_common.yaml we have

                    enum:
                      - INVALID_ARGUMENT
                      - OUT_OF_RANGE
                      - "{{SPECIFIC_CODE}}"

But in examples code and message are not written in quotes:

            GENERIC_400_{{SPECIFIC_CODE}}:
              description: Specific Syntax Exception regarding a field that is relevant in the context of the API
              value:
                status: 400
                code: { { SPECIFIC_CODE } }
                message: { { SPECIFIC_CODE_MESSAGE } }

This raises linting errors - I did the exercise to check if CAMARA_common.yaml is not propagating linting problems in API definitions. Here it is not the case because the pleaceholders should be replaced in API definitions, but to avoid this error even when linting CAMARA_common.yaml I propose to change code and message attribute:

            GENERIC_400_{{SPECIFIC_CODE}}:
              description: Specific Syntax Exception regarding a field that is relevant in the context of the API
              value:
                status: 400
                code: "{{SPECIFIC_CODE}}"
                message: Message for specific code

The same for:
GENERIC_403_{{SPECIFIC_CODE}},
GENERIC_404_{{SPECIFIC_CODE}},
GENERIC_409_{{SPECIFIC_CODE}},
GENERIC_422_{{SPECIFIC_CODE}}

[tlohmar]

Yes, LGTM

[PedroDiez]

Have proposed in commit b9f4c2e

            code: "{{SPECIFIC_CODE}}"
            message: "{{SPECIFIC_CODE_MESSAGE}}"

Also fine if you think is better to set message: Message for specific code (@rartych, @patrice-conil, @tlohmar).
Will adapt in such a case, based on your view

[PedroDiez]

Ready for review

[rartych]

LGTM

[jlurien]

LGTM

[patrice-conil]

LGTM