0

OpenApi Spec - What is the best practice that multiple microservices use the same components schema (data model) ?

Example:

Microservice1 api spec:

responses:
    $ref: '#/components/schemas/MyResponse' 

components:
   schemas:
     MyResponse:
         type: object
         required:
            true
         properties:
            myvariable1:
                   type: string
            myvariable2:
                   type: string

Microservice2 api spec:

responses: $ref: '#/components/schemas/MyResponse'

components:
   schemas:
     MyResponse:
         type: object
         required:
            true
         properties:
            myvariable1:
                   type: string
            myvariable2:
                   type: string

Is there any way that both microservices 1 and 2 can used the components schema from a centralized place? so that consistency can be maintained among both microservices?

Shashank
  • 712
  • 15
  • 33

1 Answers1

0

According to the Swagger Documentation it is possible to use three types of syntax when using $ref:

  1. Local Reference: $ref: '#/components/schemas/MyResponse'. In this notation the # character denotes the document root.
  2. Remote Reference: $ref: 'document.json#/MyResponse'. Reference other documents in the same folder or in relation to the folder.
  3. URL Reference: $ref: 'http://myservice.tld/components/schemas/definition.json#/MyResponses'. Here you can reference schemas on an entirely different server.

The exact best practice depends on how you are using your OpenAPI specification in Spring Boot, there are different ways to automatically generate API definitions (with @ControllerAdvice, @Operation, springdoc-openapi, JSR-303 Bean Validation, ...).

skowalak
  • 177
  • 10