Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update example in API-design-guidelines.md #264

Open
tanjadegroot opened this issue Aug 1, 2024 · 2 comments
Open

Update example in API-design-guidelines.md #264

tanjadegroot opened this issue Aug 1, 2024 · 2 comments
Labels
documentation Improvements or additions to documentation

Comments

@tanjadegroot
Copy link
Contributor

tanjadegroot commented Aug 1, 2024

Problem description
example should put the x-camara-commonalites field under the version field (section 11.1 Info object example) and above the description field.

Expected action

In the example (line ) move the version and x-camara-commonalities sections together, and before the description field (as this may be long)

this is a small fix - non blocking change for the next release candidate

info:
  # title without "API" in it, e.g. "Number Verification"
  title: Number Verification
  # API version - Aligned to SemVer 2.0 according to CAMARA versioning guidelines
  version: 1.0.1
  # CAMARA Commonalities version - x.y.z
  x-camara-commonalities: 0.4.0
  # description explaining the API, part of the API documentation 
  # includes text explaining how to fill the "Authorization and authentication" - see section 11.6
  description: |
    This API allows to verify that the provided mobile phone number is the one used in the device. It
    verifies that the user is using a device with the same mobile phone number as it is declared.
    ### Authorization and authentication
    CAMARA guidelines defines a set of authorization flows ...
  # Name of the license and a URL to the license description
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
@hdamker
Copy link
Collaborator

hdamker commented Aug 2, 2024

Currently the two lines are near to the server object which is a) another information which need to check in a release and b) essential information to use the API. Because of that I'm more in favor to keep the current order in the info object.

@rartych
Copy link
Collaborator

rartych commented Oct 9, 2024

@tanjadegroot I guess we can close this issue.
If needed the question can be raised when discussing changes in info object template.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

3 participants