===== 12 - Specifikace API ve Swagger =====
==== Řešení z minulého cvičení ====

[[https://gitlab.fel.cvut.cz/B211_B6B36OMO/seminar/tree/master/cv11.1_solution]]

[[https://gitlab.fel.cvut.cz/B211_B6B36OMO/seminar/tree/master/cv11.2_solution]]

[[https://gitlab.fel.cvut.cz/B211_B6B36OMO/seminar/tree/master/cv11.3_solution]]

[[https://gitlab.fel.cvut.cz/B211_B6B36OMO/seminar/tree/master/cv11.4_solution]]

==== Teorie ====

Přednáška:

OpenAPISwagger:

[[https://swagger.io/getting-started/]]

[[https://idratherbewriting.com/learnapidoc/pubapis_swagger_intro.html]]

==== 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

{{:courses:a7b36omo:labs:cv12_omolibrary.png?500|}}

<note>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.</note>
=== Hlavní body cvičení ===

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


=== Postup ===

   * V internetovém prohlížeči otevřete https://app.swaggerhub.com
   * Zaregistujte se jako nový uživatel SwaggerHub 
      {{ :courses:a7b36omo:labs:cv12_swagger_hub_1.png?700 |}}
   * Vytvořte doménu OMOLibraryDomain
      {{ :courses:a7b36omo:labs:cv12_swagger_hub_2.png?700 |}}
   * V OMOLibraryDomain v sekci **definitions:**
    - nadefinujte objekt Book
    - nadefinujte objekt Reader
    - nadefinujte objekt Address
    - nadefinujte objekt ReadingRoom
    - nadefinujte objekt Reservation
<note tip>  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]$"
</note>
<note tip>  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
</note>
<note tip>  Address
  Address:
    required:
     - city
     - zipcode
    properties:
     street: 
      type: string
     city:
      type: string
     zipcode:
      type: string
      format: zip-code
</note>
<note tip>  ReadingRoom
  ReadingRoom:
    required: 
     - readingRoomId
     - address
    properties:
     readingRoomId:
      type: integer
     address: 
      $ref: "#/definitions/Address"
</note>
<note tip>  Reservation
  Reservation:
    required:
      - readerNumber
      - readingRoomId
      - bookId
    properties:
     readerNumber:
      type: integer
     readingRoomId: 
      type: integer
     bookId:
      type: integer
</note>
   * Vytvořte novou definici API – Online Reservation
       {{ :courses:a7b36omo:labs:cv12_swagger_hub_3.png?700 |}}
   * V API - Online Reservation
     - nadefinujte REST operace GET inventory
     - nadefinujte REST operaci GET readingRoom
     - nadefinujte REST operaci POST, DELETE reservation
     - nadefinujte REST operaci POST bookAvailabitlityDate

<note tip>  /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
</note>
<note tip>  /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
</note>
<note tip>  /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  
</note>
<note tip>          
  /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
</note>


{{ :courses:a7b36omo:labs:cv12_swagger_hub_4.png?nolink&800 |}}


 
           
   * Vytvořte specifikaci API Central Archive
{{ :courses:a7b36omo:labs:cv12_swagger_hub_5.png?nolink&800 |}}

   * Vytvořte definici API Reading Room
{{ :courses:a7b36omo:labs:cv12_swagger_hub_6.png?nolink&800 |}}

   * Přejděte zpět do Online Reservation API a vygenerujte spring server implementaci: V menu Export - Server Stub vyberte Spring.
{{ :courses:a7b36omo:labs:cv12_swagger_hub_7.png?nolink&800 |}}

   * Naimportujte vygenerovaný maven projekt do vývojového prostředí
{{ :courses:a7b36omo:labs:cv12_omo_library_1.png?nolink&800 |}}

   * 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
{{ :courses:a7b36omo:labs:cv12_omo_library_2.png?nolink&800 |}}

   * Spusťte vygenerovanou implementaci příkazem mvn spring-boot:run. Poznamenejte si port, kterém microservice poslouchá (obyčejně 8080).
{{ :courses:a7b36omo:labs:cv12_omo_library_3.png?nolink&800 |}}

   * Ve SwaggerHub spusťte simulaci (Try out a Execute), prohlédněte si vygenerovaný request a očekávaný výsledek.
{{ :courses:a7b36omo:labs:cv12_omo_library_4.png?nolink&800 |}}

{{ :courses:a7b36omo:labs:cv12_omo_library_5.png?nolink&800 |}}

{{ :courses:a7b36omo:labs:cv12_omo_library_6.png?nolink&800 |}}

 
   * 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.
{{ :courses:a7b36omo:labs:cv12_omo_library_7.png?nolink&700 |}}

   * Z http://curl.haxx.se stahněte a nainstalujte curl
   * Spusťte rest volání pomocí curl příkazu
{{ :courses:a7b36omo:labs:cv12_omo_library_8.png?nolink&700 |}}