search

swissfintechinnovations / .github

SFTI organization repo
Other
0 stars 0 forks source link

OpenApi Rules #18

Open dkoeni opened 3 months ago

dkoeni commented 3 months ago

Please comment for new proposals of SFTI's naming conventions concerning the openAPI action / redocly workflow

dkoeni commented 3 months ago

body request and response parameters in snake_case according to ISO 23029

dkoeni commented 3 months ago

summary must not an with an fullstop

dkoeni commented 3 months ago

naming conventions for tags

dkoeni commented 3 months ago

Use refs for parameters or schemas used multiple times

andiahlm commented 3 months ago

Adjust ordering of root objects to redocly conventions.

openapi: info: servers: security: tags: externalDocs: paths:

Reasoning:

We use 'redocly bundle' command to build complete OAS. Redocly reorders root object according to their conventions:

andiahlm commented 3 months ago

Adapt naming-conventions for parameters to OAS common practices

Most used practice is camelCase with 'Param'-Suffix:

parameters:
  skipParam:
    name: skip
    in: query
    description: number of items to skip
    required: true
    schema:
      type: integer
      format: int32
  limitParam:
    name: limit
    in: query
    description: max records to return
    required: true
    schema:
      type: integer
      format: int32
dkoeni commented 2 months ago

Summary tag must not stop with a full stop

dkoeni commented 2 months ago

Add identifier: Apache-2.0 (SPDX license expression) to License Object

dkoeni commented 1 week ago

pattern must be of the following structure '^...$'