Skip to content
This repository has been archived by the owner on Jul 18, 2024. It is now read-only.

Commit

Permalink
Upravy v kapitolach Editacia poloziek a Navrh API specifikacie
Browse files Browse the repository at this point in the history
  • Loading branch information
Ivan Sladecka committed Jan 5, 2024
1 parent 97c5ff8 commit c818882
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 23 deletions.
20 changes: 10 additions & 10 deletions book-src/dojo/01.Web-Components/090-entry-editor-and-routing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ teraz pokračovať v implementácii funkcionality našej mikro aplikácie. V tej
...
```
V kóde si všimnite premennú `duration` a spôsob, akým pri zmene hodnoty `md-slider` elementu túto vlastnosť nastavíme na aktuálnu hodnotu. Označenie premennej dekorátorom `@Prop` alebo `@State` zabezpečí, že sa pri zmene ich hodnoty znovu vykreslí náš element s aktuálnymi hodnotami. `@Prop() entryId` deklaruje, že náš element bude obsahovať atribút s menom `entry-id`, ktorý bude určovať identifikátor záznamu, ktorý chceme upraviť. Ďalej deklarujeme, že náš element bude generovať udalosti `editor-closed` typu `CustomElement<string>`.
V kóde si všimnite premennú `duration` a spôsob, akým pri zmene hodnoty `md-slider` elementu túto vlastnosť nastavíme na aktuálnu hodnotu. Označenie premennej dekorátorom `@Prop` alebo `@State` zabezpečí, že sa pri zmene ich hodnoty znovu vykreslí náš element s aktuálnymi hodnotami. `@Prop() entryId` deklaruje, že náš element bude obsahovať atribút s menom `entry-id`, ktorý bude určovať identifikátor záznamu, ktorý chceme upraviť. Ďalej deklarujeme, že náš element bude generovať udalosti `editor-closed` typu `EventEmitter<string>`.
3. V kóde sme použili nové elementy z knižnice `@material/web`. Otvorte súbor `${WAC_ROOT}/ambulance-ufe/src/global/app.ts` a doplňte načítanie príslušných komponentov:
Expand Down Expand Up @@ -342,10 +342,10 @@ Pre účely navigácie budeme využívať [Navigation API], ktorého cieľom je
return (
<Host>
{ element === "editor"
? <pfx-ambulance-wl-editor entry-id={entryId}
? <<pfx>-ambulance-wl-editor entry-id={entryId}
oneditor-closed={ () => navigate("./list")} >
</pfx-ambulance-wl-editor>
: <pfx-ambulance-wl-list></pfx-ambulance-wl-list>
</<pfx>-ambulance-wl-editor>
: <<pfx>-ambulance-wl-list></<pfx>-ambulance-wl-list>
}

</Host>
Expand Down Expand Up @@ -429,7 +429,7 @@ Pre účely navigácie budeme využívať [Navigation API], ktorého cieľom je
5. Aby bola naša interakcia úplná, upravte súbor `${WAC_ROOT}/ambulance-ufe/src/components/pfx-ambulance-wl-list/pfx-ambulance-wl-list.tsx` a doplňte nasledujúce časti kódu:

```tsx
import { Component, Event, EventEmitter, Host, h } from '@stencil/core'; @_impotant_@
import { Component, Event, EventEmitter, Host, h } from '@stencil/core'; @_important_@
...
export class PfxAmbulanceWlList {

Expand All @@ -440,7 +440,7 @@ Pre účely navigácie budeme využívať [Navigation API], ktorého cieľom je
<Host>
<md-list>
{this.waitingPatients.map((patient, index) => @_important_@
<md-list-item onClick={ () => this.entryClicked.emit(index.toStr ())}> @_add_@
<md-list-item onClick={ () => this.entryClicked.emit(index.toString())}> @_add_@
<div slot="headline">{patient.name}</div>
<div slot="supporting-text">{"Predpokladaný vstup: " + this.isoDateToLocale(patient.estimatedStart)}</div>
<md-icon slot="start">person</md-icon>
Expand All @@ -457,9 +457,9 @@ Pre účely navigácie budeme využívať [Navigation API], ktorého cieľom je

return (
...
: <pfx-ambulance-wl-list
: <<pfx>-ambulance-wl-list
onentry-clicked={ (ev: CustomEvent<string>)=> navigate("./entry/" + ev.detail) } > @_add_@
</pfx-ambulance-wl-list>
</<pfx>-ambulance-wl-list>
...
```
Expand Down Expand Up @@ -531,7 +531,7 @@ Pre účely navigácie budeme využívať [Navigation API], ktorého cieľom je
git push
```

8. Poslednou zmenou je úprava web komponentu ktorý sa má zobraziť v micro Front-End aplikácii. K tomu nám postačí úprava konfigurácie. Otvorte súbor `${WAC_ROOT}/ambulance-gitops/apps/milung-ambulance-ufe/webcomponent.yaml` a v sekcii `navigation` zadajte nové meno elementu:
8. Poslednou zmenou je úprava web komponentu ktorý sa má zobraziť v micro Front-End aplikácii. K tomu nám postačí úprava konfigurácie. Otvorte súbor `${WAC_ROOT}/ambulance-gitops/apps/<pfx>-ambulance-ufe/webcomponent.yaml` a v sekcii `navigation` zadajte nové meno elementu:

```yaml
navigation:
Expand All @@ -549,7 +549,7 @@ Pre účely navigácie budeme využívať [Navigation API], ktorého cieľom je
git push
```

Pokiaľ nie je Váš [Docker Desktop] klaster aktívny, naštartujte ho. Po chvíli, keď operátor [Flux CD] obnoví všetky zmeny - obnovenie verzie obrazu, nasadenie zmien v konfigurácii, prejdite na stránku [http://localhost:30331](http://localhost:30331) a následne vyberte aplikáciu _Zoznam čakajúcich ..._. Mala by sa Vám zobraziť stránka s komponentom `<pfx>-ambulance-wl-list`. Po kliknutí na záznam by sa Vám mal zobraziť editor záznamu. Po stlačení na tlačidlo "Zrušiť" by ste sa mali vrátiť na zoznam čakajúcich. Hoci sme v súbore `${WAC_ROOT}/ambulance-gitops/apps/milung-ambulance-ufe/webcomponent.yaml` explicitne nenastavili atribút `base-path`, tento je k elementu automaticky pridávaný službou `ufe-controller` na základe hodnoty atribútu `path` .
Pokiaľ nie je Váš [Docker Desktop] klaster aktívny, naštartujte ho. Po chvíli, keď operátor [Flux CD] obnoví všetky zmeny - obnovenie verzie obrazu, nasadenie zmien v konfigurácii, prejdite na stránku [http://localhost:30331](http://localhost:30331) a následne vyberte aplikáciu _Zoznam čakajúcich ..._. Mala by sa Vám zobraziť stránka s komponentom `<pfx>-ambulance-wl-list`. Po kliknutí na záznam by sa Vám mal zobraziť editor záznamu. Po stlačení na tlačidlo "Zrušiť" by ste sa mali vrátiť na zoznam čakajúcich. Hoci sme v súbore `${WAC_ROOT}/ambulance-gitops/apps/<pfx>-ambulance-ufe/webcomponent.yaml` explicitne nenastavili atribút `base-path`, tento je k elementu automaticky pridávaný službou `ufe-controller` na základe hodnoty atribútu `path` .

>build_circle:> V prípade problémov s nasadením zmien v konfigurácii môžete overiť stav jednotlivých objektov v klastri príkazmi:
>
Expand Down
28 changes: 15 additions & 13 deletions book-src/dojo/01.Web-Components/101-openapi.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ V predchádzajúcej sekcii ste si určite všimli, že náš editor sa vždy zob
license:
name: CC BY 4.0
url: "https://creativecommons.org/licenses/by/4.0/"
tags:
tags:
- name: ambulanceWaitingList @_important_@
description: Ambulance Waiting List API
```
Expand All @@ -45,7 +45,7 @@ V predchádzajúcej sekcii ste si určite všimli, že náš editor sa vždy zob
- ambulanceWaitingList @_important_@
summary: Provides the ambulance waiting list
operationId: getWaitingListEntries @_important_@
description: By using ambulanceId you get list of entries in ambulance witing list
description: By using ambulanceId you get list of entries in ambulance waiting list
parameters:
- in: path @_important_@
name: ambulanceId @_important_@
Expand All @@ -66,7 +66,7 @@ V predchádzajúcej sekcii ste si určite všimli, že náš editor sa vždy zob
response:
$ref: "#/components/examples/WaitingListEntriesExample" @_important_@
"404":
description: Ambulance with such ID does not exists
description: Ambulance with such ID does not exist
```

Táto špecifikácia určuje, že na ceste `/waiting-list/{ambulanceId}/entries`, kde `{ambulanceId}` je premenná hodnota typu string, môžeme vyvolať požiadavku typu [HTTP GET](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET), ktorej odozva môže nadobudnúť hodnotu [200](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) alebo [404](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404), pričom v prvom prípade bude obsahovať pole objektov typu `WaitingListEntry`. Tiež sme určili meno operácie `getWaitingListEntries`. Toto meno určuje názov metód a funkcií pri generovaní kódu. Názov `operationId` musí byť v rámci špecifikácie jedinečný. Všimnite si tiež, že sme použili referencie na sekciu `components`. Vložme teraz do súboru [JSON schému][jsonschema] pre objekt `WaitingListEntry` a pre objekty, na ktorých je závislý:
Expand Down Expand Up @@ -137,7 +137,7 @@ V predchádzajúcej sekcii ste si určite všimli, že náš editor sa vždy zob

V tejto špecifikácii sme zadefinovali objekt `WaitingListEntry`, ktorý obsahuje všetky potrebné informácie o zozname čakajúcich pacientov a opis zdravotného problému pacienta definovaný typom `Condition`. Technicky by sme mohli schému vnoreného typu `Condition` definovať priamo v objekte `WaitingListEntry`. Pre účely generovania kódu a pre prehľadnosť ale odporúčame vždy používať referencie na samostatne definované typy. Dôležitým aspektom špecifikácie je uvádzanie povinných polí pomocou kľúčového slova `required`. Toto kľúčové slovo je dôležité pre generovanie kódu, ktorý bude validovať vstupné dáta. V prípade, že vstupné dáta nebudú obsahovať povinné polia, tak požiadavka bude typicky odmietnutá so stavovým kódom [400 - Bad Request](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400).

V špecifikácii konzistentne uvádzame príklady s použitím kľúčového slova `example`. Tieto príklady sú dôležité pre generovanie dokumentácie a sú tiež dôležité pre vytvorenie experimentálnej služby (_mock_), ktorú budeme používať pri lokálnom vývoji. Doplňte do súboru nasledujúce príklady do sekcie `components.example`:
V špecifikácii konzistentne uvádzame príklady s použitím kľúčového slova `example`. Tieto príklady sú dôležité pre generovanie dokumentácie a sú tiež dôležité pre vytvorenie experimentálnej služby (_mock_), ktorú budeme používať pri lokálnom vývoji. Doplňte do súboru nasledujúce príklady do sekcie `components.examples`:

```yaml
components:
Expand Down Expand Up @@ -198,7 +198,7 @@ V predchádzajúcej sekcii ste si určite všimli, že náš editor sa vždy zob

>info:> Naše API `getWaitingListEntries` vracia priamo pole záznamov, čo je v prípade WebAPI považované za chybu návrhu. Naše API by malo byť pripravené aj pre väčší rozsah dát a podporovať získanie len ich [čiastočného rozsahu](https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design#filter-and-paginate-data). Pre zjednodušenie ale tento aspekt nebudeme v našej aplikácii riešiť, pri návrhu konkrétneho API v praxi sa ale najprv zoznámte so [zásadami návrhu RESTfull API](https://book.restfulnode.com/).

3. V prvom kroku si pripravíme experimentálny - _mock_ - server poskytujúci špecifikované API na základe príkladov v špecifikácii. Nainštalujte do projektu nové závislosti potrebné pre vývoj aplikácie:
3. V prvom kroku si pripravíme experimentálny - _mock_ - server poskytujúci špecifikované API na základe príkladov v špecifikácii. Nainštalujte do projektu nové závislosti potrebné pre vývoj aplikácie spustením nasledovného príkazu v priečinku `${WAC_ROOT}/ambulance-ufe`:

```ps
npm install --save-dev js-yaml open-api-mocker npm-run-all
Expand All @@ -221,7 +221,7 @@ V predchádzajúcej sekcii ste si určite všimli, že náš editor sa vždy zob

>$apple:> Na niektorých Mac zariadeniach môže na porte 5000 bežať airplay server. V takomto prípade zmeňte port mock serveru na iný voľný port.

Skript `convert-openapi` premení špecifikáciu vo formáte YAML na JSON - `open-api-mocker` vyžaduje špecifikáciu vo formáte JSON. Skript `mock-api` spustí mock server, ktorý bude poskytovať API podľa špecifikácie. Skript `start:mock` spustí obe predchádzajúce príkazy sekvenčne. Skript `start:app` obsahuje príkaz, pôvodne použitý v skripte `start`, teda skompiluje našu aplikáciu a naštartuje vývojový server. Skript `start` sme upravili, aby paralelne spustil náš mock API server a vývojový server našej aplikácie. Tieto úpravy nám umožnia lokálny vývoj aplikácie bez nutnosti pripojenia na skutočný API server.
Skript `convert-openapi` premení špecifikáciu vo formáte YAML na JSON - `open-api-mocker` vyžaduje špecifikáciu vo formáte JSON. Skript `mock-api` spustí mock server, ktorý bude poskytovať API podľa špecifikácie. Skript `start:mock` spustí oba predchádzajúce príkazy sekvenčne. Skript `start:app` obsahuje príkaz, pôvodne použitý v skripte `start`, teda skompiluje našu aplikáciu a naštartuje vývojový server. Skript `start` sme upravili, aby paralelne spustil náš mock API server a vývojový server našej aplikácie. Tieto úpravy nám umožnia lokálny vývoj aplikácie bez nutnosti pripojenia na skutočný API server.

Upravte súbor `${WAC_ROOT}/ambulance-ufe/.gitignore` a pridajte riadok `.openapi.json`.

Expand Down Expand Up @@ -311,13 +311,13 @@ V predchádzajúcej sekcii ste si určite všimli, že náš editor sa vždy zob
5. Vygenerované API použijeme v našej aplikácii. Najprv doinštalujeme knižnicu [Axios], ktorú využíva vygenerovaný klientský kód:

```ps
npm install --save axios
npm install --save axios@1.6.0
```

Otvorte súbor `${WAC_ROOT}/ambulance-ufe/src/components/<pfx>-ambulance-wl-list/<pfx>-ambulance-wl-list.tsx` a upravte kód:

```tsx
import { Component, Event, EventEmitter, Host, Prop, State, h } from '@stencil/core';
import { Component, Event, EventEmitter, Host, Prop, State, h } from '@stencil/core'; @_important_@
import { AmbulanceWaitingListApiFactory, WaitingListEntry } from '../../api/ambulance-wl'; @_add_@
...
export class <Pfx>AmbulanceWlList {
Expand Down Expand Up @@ -467,7 +467,7 @@ V predchádzajúcej sekcii ste si určite všimli, že náš editor sa vždy zob

Opäť vykonajte príkaz `npm run test` a tentokrát by testy mali prebehnúť úspešne.

9. Pokiaľ si prezrieme test v súbore `${WAC_ROOT}/ambulance-ufe/src/components/pfx-ambulance-wl-list/test/pfx-ambulance-wl-list.spec.tsx`, pochopíme, že náš test je úspešný len z dôvodu, že pri neúspešnom pripojení sa k serveru je zoznam pacientov prázdny. Bolo by preto vhodnejšie, keby sme boli schopní simulovať spojenie s API serverom. Na to použijeme knižnicu [axios-mock-adapter](https://github.com/ctimmerm/axios-mock-adapter). Nainštalujte si túto knižnicu do projektu:
9. Pokiaľ si prezrieme test v súbore `${WAC_ROOT}/ambulance-ufe/src/components/pfx-ambulance-wl-list/test/pfx-ambulance-wl-list.spec.tsx`, pochopíme, že náš test bude úspešný aj pri neúspešnom pripojení sa k serveru, kedy je zoznam pacientov prázdny. Bolo by preto vhodnejšie, keby sme boli schopní simulovať spojenie s API serverom. Na to použijeme knižnicu [axios-mock-adapter](https://github.com/ctimmerm/axios-mock-adapter). Nainštalujte si túto knižnicu do projektu:

```ps
npm install --save-dev axios-mock-adapter
Expand Down Expand Up @@ -563,7 +563,7 @@ V predchádzajúcej sekcii ste si určite všimli, že náš editor sa vždy zob
10. (_Voliteľné_) Pokiaľ chcete využívať testovacie prostredie [Jest] priamo, napríklad chcete využiť niektoré z populárnych rozšírení ako napríklad [vscode-jest](https://marketplace.visualstudio.com/items?itemName=Orta.vscode-jest), doplňte do projektu konfiguráciu pre správny beh [jest cli](https://jestjs.io/docs/cli) nástrojov. Vytvorte súbor `${WAC_ROOT}/ambulance-ufe/jest.config.js` s nasledujúcim obsahom:

```js
export default {
module.exports = {
"roots": [
"<rootDir>/src"
],
Expand Down Expand Up @@ -603,7 +603,7 @@ V predchádzajúcej sekcii ste si určite všimli, že náš editor sa vždy zob
git push
```

Po vytvorení novej verzie obrazu sa táto nasadí na server. Pokiaľ máte klaster naštartovaný, môžete overiť funkcionalitu na stránke [http://localhost:3031](http://localhost:3031). V tomto prípade ale ešte nemáme nastavené správne atribúty pre našu aplikáciu. Otvorte súbor `${WAC_ROOT}/ambulance-gitops/apps/milung-ambulance-ufe/webcomponent.yaml` a pridajte atribúty `api-base` a `ambulance-id`:
Po vytvorení novej verzie obrazu sa táto nasadí na server. Pokiaľ máte klaster naštartovaný, môžete overiť funkcionalitu na stránke [http://localhost:30331](http://localhost:30331). V tomto prípade ale ešte nemáme nastavené správne atribúty pre našu aplikáciu. Otvorte súbor `${WAC_ROOT}/ambulance-gitops/apps/<pfx>-ambulance-ufe/webcomponent.yaml` a pridajte atribúty `api-base` a `ambulance-id`:

```yaml
...
Expand All @@ -618,7 +618,7 @@ V predchádzajúcej sekcii ste si určite všimli, že náš editor sa vždy zob
hash-suffix: v1alpha2 @_important_@
```

>$apple:> Nezabudnite nastaviť správny port.
>$apple:> Ak ste predtým zmenili číslo portu, nezabudnite aj tu nastaviť správny port.

Následne v priečinku `${WAC_ROOT}/ambulance-gitops` vykonajte komit a push:

Expand All @@ -628,4 +628,6 @@ V predchádzajúcej sekcii ste si určite všimli, že náš editor sa vždy zob
git push
```

Po aplikovaní zmien bude funkčnosť Vášho zoznamu závisieť od prítomnosti Vášho mock API - z pohľadu prehliadača je `localhost` adresa Vášho počítača.
Po uplynutí času nutného na aplikovanie zmien do klastra overte funkcionalitu na stránke [http://localhost:30331](http://localhost:30331). Na obrazovke vidíte chybové hlásenie. Dôvodom je, že neprechádza volanie na server. Presvedčte sa o tom skontrolovaním záložky `Sieť` v paneli `Nástroj pre vývojárov`, kde môžte vidieť neúspešné volanie API `http://localhost:5000/api/waiting-list/bobulova/entries`. Volanie zlyhá z dôvodu porušenia CSP pravidiel (vysvetlíme a vyriešime v ďalších kapitolách).

Avšak aj v prípade, ak by sme vyriešili CSP problém, volanie na server nebude funkčné. Dôvodom je, že na adrese `localhost:5000` nie je spustený server. Môžeme ho simulovať spustením príkazu `npm run start:mock`.

0 comments on commit c818882

Please sign in to comment.