12 - Specifikace API ve Swagger

Řešení z minulého cvičení

Teorie

Zadání

Připravte specifikace rozhraní komponent knihovního systému, který umožňuje čtenáři online rezervaci vypůjčení knihy ve vybrané čítárně.

Systém umožní vyhledat knihu v inventáři knih, vyhledat a vybrat čítárnu, kde si čtenář knihu vypůjčí a provést rezervaci. Rezervovanou knihu pak knihovna distribuuje z centrálního archivu do konkrétní čítárny, kde ji čtenář dostane k dispozici.

Řešení systému bude v architektonickém stylu microservice. Komunikačním protokolem mezi microservice bude REST API.

Systém bude složený z následujících microservice:

Online Reservation – umožňuje najít knihu v registru centrálního systému, rezervovat knihu, udržuje informace o stavu rezervace

Central Archive – spracuje centrální registr knih, eviduje distribuci knihy do čítárny

Reading Room - eviduje knihy, které přišly z centrálního skladu, spravuje vypůjčení knihy čtenářem

Cílem cvičení není udělat kompletní návrh řešení, ale projít důležité body v použití Swagger pro návrh rozhraní až po vygenerování kódu microservice.

Hlavní body cvičení

  1. Pomocí SwagerHub nadefinujte doménový model knihovního systému a definice REST rozhraní microservice Online Reservation, Central Archive, Reading Room.
  2. Ze SwaggerHub vygenerujte spring projekt a prohlédněte si vygenerovanou implementaci.
  3. Spusťte microservice a vyzkoušejte funkčnost REST API.

Postup

  • Vytvořte doménu OMOLibraryDomain

  • V OMOLibraryDomain v sekci definitions:
    1. nadefinujte objekt Book
    2. nadefinujte objekt Reader
    3. nadefinujte objekt Address
    4. nadefinujte objekt ReadingRoom
    5. nadefinujte objekt Reservation
Book
 Book:
  description: "Kniha, kterou si může čtenář vypůjčit."
  required:
   - title
   - author
   - isbn
  properties:
   bookId:
    type: integer
   title:
    type: string
   author: 
    type: string
   numberOfPages:
    type: integer
    format: int32
   isbn:
    type: string
    pattern: "^(?:ISBN(?:-10)?:?)?(?=[0-9X]{10}$|(?=(?:[0-9]+[- ]){3})[- 0-9X]{13}$)[0-9]{1,5}[- ]?[0-9]+[- ]?[0-9]+[- ]?[0-9X]$"
Reader
 Reader:
  description: "Čtenář, který si bude půjčovat knihy."
  required:
   - readerNumber
   - firstname
   - lastname
   - email
  properties:
   readerNumber:
    type: integer
   firstname: 
    type: string
   lastname:
    type: string
   email:
    type: string
Address
Address:
  required:
   - city
   - zipcode
  properties:
   street: 
    type: string
   city:
    type: string
   zipcode:
    type: string
    format: zip-code
ReadingRoom
ReadingRoom:
  required: 
   - readingRoomId
   - address
  properties:
   readingRoomId:
    type: integer
   address: 
    $ref: "#/definitions/Address"
Reservation
Reservation:
  required:
    - readerNumber
    - readingRoomId
    - bookId
  properties:
   readerNumber:
    type: integer
   readingRoomId: 
    type: integer
   bookId:
    type: integer
  • Vytvořte novou definici API – Online Reservation

  • V API - Online Reservation
    1. nadefinujte REST operace GET inventory
    2. nadefinujte REST operaci GET readingRoom
    3. nadefinujte REST operaci POST, DELETE reservation
    4. nadefinujte REST operaci POST bookAvailabitlityDate
/inventory:
  get:
    tags:
    - users
    summary: searches inventory
    operationId: searchInventory
    description: |
      By passing in the appropriate options, you can search for
      available inventory in the system
    produces:
    - application/json
    parameters:
    - in: query
      name: searchString
      description: pass an optional search string for looking up inventory
      required: false
      type: string
    - in: query
      name: skip
      description: number of records to skip for pagination
      type: integer
      format: int32
      minimum: 0
    - in: query
      name: limit
      description: maximum number of records to return
      type: integer
      format: int32
      minimum: 0
      maximum: 50
    responses:
      200:
        description: search results matching criteria
        schema:
          type: array
          items:
            $ref: 'https://api.swaggerhub.com/domains/Tomas-Mayer/OMOLibraryDomain/1.0.0#/definitions/Book'
      400:
        description: bad input parameter
/readingRoom:
  get:
    tags:
    - users
    summary: searches reading room
    operationId: searchReadingRoom
    description: Return a list of reading rooms. 
    produces:
    - application/json
    parameters:
    - in: query
      name: searchString
      description: pass an optional search string for looking up reding room
      required: false
      type: string
    - in: query
      name: skip
      description: number of records to skip for pagination
      type: integer
      format: int32
      minimum: 0
    - in: query
      name: limit
      description: maximum number of records to return
      type: integer
      format: int32
      minimum: 0
      maximum: 50
    responses:
      200:
        description: search results matching criteria
        schema:
          type: array
          items:
            $ref: 'https://api.swaggerhub.com/domains/Tomas-Mayer/OMOLibraryDomain/1.0.0#/definitions/ReadingRoom'
      400:
        description: bad input parameter
/reservation:
  post:
    tags:
      - users
    summary: adds a new reservation of book
    operationId: addReservation
    description: reserve a book for reader
    consumes:
      - application/json
    produces:
      - application/json
    parameters:
    - in: body
      name: reservation
      description: the reservation details
      schema: 
          $ref: 'https://api.swaggerhub.com/domains/Tomas-Mayer/OMOLibraryDomain/1.0.0#/definitions/Reservation'
    responses:
      201:
        description: item created
      400:
        description: invalid input, object invalid
      409:
        description: an existing item already exists
   delete:
    tags:
      - users
    summary: removes an existing reservation of book
    operationId: deleteReservation
    description: deleta a reservation
    consumes:
      - application/json
    produces:
      - application/json
    parameters:
    - in: body
      name: reservation
      description: the reservation details
      schema: 
          $ref: 'https://api.swaggerhub.com/domains/Tomas-Mayer/OMOLibraryDomain/1.0.0#/definitions/Reservation'
    responses:
      201:
        description: item created
      400:
        description: invalid input, object invalid
      410:
        description: a requested item does not exists  
/bookAvailability:
  post:
    tags:
      - admins
    summary: posts a date when the book is available in requested reading room
    operationId: postBookAvailability
    description: posts a date when the book is available in requested reading room
    consumes:
      - application/json
    produces:
      - application/json
    parameters:
    - in: body
      name: reservationDate
      schema: 
        $ref: "#/definitions/ReservationDate"
    responses:
      201:
        description: item created
      400:
        description: invalid input, object invalid
      410:
        description: the reservation does not exist          
  definitions:
     ReservationDate:
      properties:
        reservation:
          $ref: 'https://api.swaggerhub.com/domains/Tomas-Mayer/OMOLibraryDomain/1.0.0#/definitions/Reservation'
        date:
         type: string
         format: date

  • Vytvořte specifikaci API Central Archive

  • Vytvořte definici API Reading Room

  • Přejděte zpět do Online Reservation API a vygenerujte spring server implementaci: V menu Export - Server Stub vyberte Spring.

  • Naimportujte vygenerovaný maven projekt do vývojového prostředí

  • Projděte vygenerovanou implementaci a v třídě InventoryApiController najděte operaci searchInventory, operaci upravte tak, aby vracela seznam knih nejen pro content-type application/json

  • Spusťte vygenerovanou implementaci příkazem mvn spring-boot:run. Poznamenejte si port, kterém microservice poslouchá (obyčejně 8080).

  • Ve SwaggerHub spusťte simulaci (Try out a Execute), prohlédněte si vygenerovaný request a očekávaný výsledek.

  • Request vygenerovaný v předchozím kroku zadejte do internetového prohlížeče. Jako host zadejte localhost a port, na kterém poslouchá spring microservice (například: http://localhost:8080/…….) a zkontrolujte výsledek.

  • Z http://curl.haxx.se stahněte a nainstalujte curl
  • Spusťte rest volání pomocí curl příkazu

courses/b6b36omo/labs/lab122017.txt · Last modified: 2023/12/19 09:11 by vankejan