OpenAPI Specifications

There must be a single OAS document (.yaml) for every subdomain, this means that the versioning will be done on the entire subdomain.

The following structure is the fragmentation of the complete OAS document which represents a subdomain. The fragmentation provides order, readability, and eases the modification of the prototype making it more usable.

Once all the fragments are correctly compiled, one can produce the complete OAS document by using Swagger-CLI and running: swagger-cli bundle <openaapi-definition-file-name> --outfile <output-file-name> --type yaml

The generated file will be ready to be used for code generation, postman, api-gateway, etc.

OAS Project structure

openapi-[DOMAIN-PLACEHOLDER].yaml

• servers contains the definition of the API Gateway server URL

  • Might also contain the base path of all APIs in the domain/subdomain, i.e. /domain/subdomain/...

• tags must be used to define the resources in the domain/subdomain

• paths definition points to other YAMLs, there will typically be 2 paths per resource, one singular and one plural

• components definition points to other YAMLs placed inside the schemas/ folder

  • schemas: all Objects used to design the APIs

    • One common YAML for common Objects (to be documented in a dedicated Confluence page)

    • One YAML dedicated to each domain/subdomain

    • Each property must have

      • type

      • description

    • For taxonomy tables (L class tables) properties MUST specify an enum with all possible values as examples

  • responses: all responses Objects (for private API suite only specific common errors)

    • One common YAML dedicated to common responses if needed

  • securitySchemes: all security schemes

    • oOne common YAML dedicated to common security schemes

• The README.md file in each domain will describe the domain itself, what it is, what is does

Operations

• tags: specify the correct Tag to which the operation belongs

• summary: README becomes the title of the operation

  • GET

    • Get a resource

    • Get multiple resources

    • Search resources

  • POST

    • Create a resource

  • PATCH

    • Update a resource

  • PUT

    • Upsert a resource

  • DELETE

    • Delete a resource

• description*: Short (2/3 sentences) description of what the operation does. Plus a link to the technical documentation on Confluence

• operationId: Not visible, it must be a unique ID which identifies the operation. If not specified it is auto-generated. Always specify it and use a semantically correct definition, try to use Java-like syntax and semantic.

• parameters: PATH parameters to be specified

  • name:

  • in: path/query

  • required:

  • style: [only for query]

  • explode: [only for query]

  • description: [check if only for query]

  • schema

    • type: one of the OAS allowed types

• requestBody:

  • reference to the external YAML definition file

  • at least one request example

• responses: Every possible response w/o the common ones (e.g. 200/201/400/401/404/etc)

  • description: What the response contains

  • content:

    • [content-type]: (typically application/json)

      • schema: $ref to the response Object in the correct YAML file

  • When executing a process/action/intent/update always 200

    • Always specify at least one example of the response

    • If there is no body in the response use 204 No Content

  • When creating something always 201

    • Always return a body containing the ID or the IDs related to the resource/s

  • When doing an async process always 202

  • links: HATEOAS could be used to specify which are the related resources (e.g. wo-operation -> materials)

  • Errors are typically common responses, therefore not specified. DTOResponse with the proper functional error definition and description. Try to include the Object in the commons definition.

• security: typically JWT bearer token, defined in the separate YAML file