Verktyg för APIdokumentation
Tool for API documentation
Jonathan Hagberg Martin Gårdebratt
Fakulteten för hälsa, naturoch teknikvetenskap Datavetenskap
Cuppsats 15hp
Handledare: Kerstin Andersson Examinator: KarlJohan Grinnemo Datum: 20210601
Förord
Vi vill tacka Kerstin Andersson från Karlstads Universitet för all hjälp och handledning i uppsatsskrivandet och för ett genuint visat intresse av projektet. Vidare vill vi även tacka Askås för att vi fick utföra examensarbetet hos dem. Slutligen vill vi tacka våra handledare Anton Danielsson och Philip Heimer från Askås för all hjälp vi fått under arbetets gång.
i
Sammanfattning
Med ett ökat antal API:er på internet ökar även behovet av anvisningar kring dessa.
När användarna för API:er har olika nivåer av erfarenhet blir den nödvändiga doku- mentationen och instruktionerna svårare att precisera från en utvecklares perspektiv. I detta projekt är målet att fastställa vad som utgör en bra dokumentation för ett API och tillämpa det för ett existerande API på begäran av Askås. Det befintliga materialet analyserades för att bygga en bättre förståelse för vilka API-anrop som stöttades, och skulle byggas om på ett sådant sätt att det skulle vara enkelt att implementera i Askås nya dokumentationssida. För att få klarhet kring vad som utgör bra API-dokumentation undersöktes fältstudier. Givet detta kunde arbetet utföras enligt etablerade studier till- sammans med kontinuerlig feedback från uppdragsgivaren. Resultatet är ett verktyg som kan användas för att göra API-anrop där parametrarna är förklarade på ett dynamiskt sätt som är byggt i React, uttryckt i Docusaurus, i väntan på att bli sammansatt i Askås nya dokumentationssida.
iii
Abstract
As the number of APIs on the internet increases, so does the need for guidance on how to use these. In APIs where the users have varying experience, the necessary documentation and instructions needed becomes harder to pinpoint from a developer’s point of view. In this project, the objective is to conclude what constitutes a good documentation for an API and apply it to an existing API, as requested from Askås.
The pre-existing material was analysed to build an understanding for which API calls were supported, and was to be re-built in such a way that it would be easily implemented in Askås’ new API documentation site. To bring clarity to what constitutes good API documentation, field studies were examined. With this, the project could be executed according to the examined studies, as well as feedback from the client. The result is a tool that can be used to make API calls where the parametres are explained in a dynamic fashion - developed in React, expressed in Docusaurus, waiting to be merged into Askås new documentation site.
v
Innehåll
Förord i
Sammanfattning iii
Abstract v
Figurer xii
1 Introduktion 1
1.1 Bakgrund . . . 1
1.2 Problembeskrivning . . . 6
1.3 Syfte och mål . . . 6
1.4 Etik och samhälle . . . 6
1.5 Metod . . . 7
1.6 Fördelning av arbete . . . 7
1.7 Uppdragsgivare . . . 8
1.8 Avgränsningar . . . 8
1.9 Disposition . . . 8
2 Bakgrund 11 2.1 Webb-API . . . 11
2.2 API-dokumentation . . . 12 vii
2.2.1 API-dokumentationens syfte . . . 12
2.2.2 Problemen med API-dokumentation . . . 13
2.3 React . . . 14
2.3.1 Introduktion till React . . . 14
2.3.2 Virtual-DOM . . . 15
2.3.3 Render . . . 16
2.4 Markdown . . . 17
2.5 Docusaurus . . . 19
2.6 Node.js . . . 19
2.7 Analys av problembeskrivning . . . 19
3 Implementation 21 3.1 Installation . . . 21
3.1.1 Node Package Manager och Yarn . . . 21
3.1.2 Npx och React-app . . . 22
3.1.3 Docusaurus-app . . . 22
3.2 Befintligt verktyg . . . 23
3.3 Design . . . 24
3.3.1 Principiell design . . . 24
3.3.2 Design React . . . 24
3.3.3 Design Docusaurus . . . 25
3.4 Utveckling av huvudkomponenten . . . 27
3.4.1 Anropet . . . 27
3.4.2 Forma ett anrop . . . 29
3.4.3 Händelser . . . 30
3.5 Dokumentation . . . 31
3.6 Interaktion mellan Markdown och React . . . 33
3.7 Dokumentationskomponenten . . . 35
INNEHÅLL ix
4 Resultat 37
4.1 Projektstruktur . . . 37
4.1.1 Arkitektur . . . 37
4.1.2 UML-diagram . . . 38
4.2 Slutgiltig version . . . 39
4.3 Begränsningar . . . 44
4.3.1 Projektet . . . 44
4.3.2 Docusaurus . . . 44
4.4 Problem . . . 44
4.4.1 CORS . . . 45
4.4.2 Hashfunktionen . . . 45
4.5 Utvärdering . . . 45
5 Slutsats 49 5.1 Diskussion . . . 49
5.2 Fortsatt arbete . . . 50
5.3 Summering . . . 50
5.4 Personliga reflektioner . . . 51
Litteraturförteckning 52
Figurer
1.1 Tillväxten över tid för webb-API:er [3] . . . 2 1.2 Resultat över de mest älskade webbramverken från undersökningen [6] 3 1.3 Resultat över de mest fruktade webbramverken från undersökningen [6] 4 1.4 Resultat över de mest eftersökta webbramverken från undersökningen [6] 4 2.1 En komponent som gör ett fetch-anrop vid knapptryck . . . 15 2.2 Den övre figuren representerar JSX och den undre figuren JavaScript-kod 17 2.3 Markdown-kod för sidan thank-you.md som genereras av Docusaurus
vid skapande av en Docusaurus-sida . . . 18 2.4 Samma sida som i figur 2.3 uttryckt i HTML-kod . . . 18 3.1 Det befintliga verktyget som används av Askås . . . 23 3.2 Standardiserad design på ett Docusaurus-projekt med classic-mall . . . 25 3.3 Mappstruktur på ett Docusaurus-projekt med classic-mall vid namn my-
website . . . 26 3.4 Hur urvalet av olika API-anrop presenteras . . . 27 3.5 Det första anropet som gjordes under utvecklingen av komponenten . . 27 3.6 Render-funktionen som renderar en knapp om dataLoaded är false, an-
nars skrivs resultatet ut . . . 28 3.7 Utseende före respektive efter knapptryck . . . 28 3.8 Exempel på parametrar som fetch kan använda sig av . . . 29
xi
3.9 En textarea som innehåller ett exempel på ett ping-anrop . . . 30
3.10 Funktionen som anropas då en förändring i textarean sker . . . 31
3.11 Hur svaret sparas undan . . . 31
3.12 Svaret som ges av ett ping-anrop . . . 32
3.13 Tabell för viktiga parametrar i ping-anropet . . . 33
3.14 Hur man implementerar en React-komponent i MDX . . . 33
3.15 Fälten som passeras från en MDX-fil till React-komponenterna . . . 34
3.16 Konstruktorn för huvudkomponenten . . . 34
3.17 Koden for komponenten som presenterar dokumenteringen av anropet . 36 4.1 Strukturen för det nya verktyget . . . 38
4.2 UML-diagram för den slutgiltiga versionen . . . 39
4.3 Sidofältet för verktyget . . . 40
4.4 Anropet Get article från det nya verktyget . . . 41
4.5 Konstruktor för huvudkomponenten . . . 42
4.6 Funktioner för huvudkomponenten . . . 43
4.7 Render för huvudkomponenten . . . 43
Kapitel 1
Introduktion
Det här kapitlet redogör grunderna för examensarbetet och tar upp relevant statistik som används som berättigande för arbetet. Detta följs av en problembeskrivning som lägger grunden för projektet. Vidare förklaras syftet med arbetet, följt av en analys av de etiska aspekterna för detta. Fortsättningsvis beskrivs hur projektet utförts och fördelats mellan de två inblandade parterna. Som avslut ges de avgränsningarna satta för arbetet och en disposition för följande kapitel.
1.1 Bakgrund
Ett API (Application Programming Interface) är ett gränssnitt som agerar medium mel- lan olika mjukvaruprodukter, som exempelvis applikation eller webbsida, och spelar en viktig roll i mjukvaruutveckling. I enkla termer kan det förklaras som en uppsättning funktioner och metoder som tillåter skapande av applikationer som har åtkomst till data och resurser som andra applikationer erhåller. Ett API är däremot inget nytt koncept - företaget eBay lanserade sitt API redan år 2000 [1], och sedan dess har de växt i popularitet. Under 2012 beräknade GetElastic och Monetate att det skulle finnas 30 000 API:er år 2016 [2]. Den faktiskta siffran blev ungefär hälften så stor, men trots
1
det så har inte tillväxten stannat av, utan trendar uppåt. ProgrammableWeb har samlat data över tillväxten för webb-baserade API:er sedan 2005, demonstrerat i figur 1.1 [3]. Mätningen, som är från 2019, visar att tillväxten ökar, och i juni 2019 uppnåddes markören för 22 000 API:er.
Figur 1.1: Tillväxten över tid för webb-API:er [3]
När ett API utvecklas är det viktigt att tänka på vem som ska använda API:t. Ef- tersom ett API kan ses som ett verktyg underlättar det med instruktioner över hur tillver- karen har tänkt att detta skall användas [4]. På grund av hur stor påverkan dokumentation har på användandet av API:t har kan detta anses vara svårare än att implementera kod, eftersom vilken produkt som helst fallerar om ingen vet hur man använder den. En bra dokumentation underlättar upplevelsen för användaren, varför det är viktigt att ha i åtanke för utvecklaren [5].
Stack Overflow är den största resursen online för professionella utvecklare och entusiaster för att lära sig, hjälpa och dela med kod. Den årliga undersökningen för ut- vecklare är den största undersökningen av dess like för utvecklare över hela världen. År
1.1. BAKGRUND 3 2020 deltog 65000 utvecklare där det bland annat gavs svar på vilka webbgränssnitt som är mest älskade, mest fruktade och mest eftersökta [6]. Mest eftersökta i denna mening innebär utvecklare som inte arbetat med teknologin, men har ett uttryckt intresse över att göra det i framtiden. Figurerna 1.2, 1.3 och 1.4 visar resultaten från undersökningen.
Figur 1.2: Resultat över de mest älskade webbramverken från undersökningen [6]
Figur 1.3: Resultat över de mest fruktade webbramverken från undersökningen [6]
Figur 1.4: Resultat över de mest eftersökta webbramverken från undersökningen [6]
1.1. BAKGRUND 5 I figurerna ses att React har haft en stor påverkan på utvecklingsvärlden sedan det släpptes år 2013 när det kommer till webbapplikationer och dess användargränssnitt, och används idag av några av de största företagen på internet [7]. Nedan följer en lista över några företag som använder React.
• Atlassian
• AirBnB
• BBC
• Dropbox
• Netflix
• PayPal
• Spotify
• Twitch
• Uber
• Yahoo
Dessa är endast några av de dryga fyra miljoner webbsidor som enligt statistik använder React. Vid anblick av denna statistik syns det att av de 10 000 mest populära webbsidor som finns använder 39,25% React i någon form [8]. Detta är en anmärkningsvärd siffra som motiverar ett djupare dyk inom React.
På grund av dess popularitet finns det utvecklade verktyg som har stöd för React.
Ett av dessa verktyg är Docusaurus, som är en tjänst som genererar webbsidor med avseende att utföra dokumentering. Docusaurus har stöd för “React-komponenter” och kan implementeras i MDX, som är ett skrivbart format där Markdown och JSX (Ja- vaScript blandat med HTML) kombineras [9]. En React-komponent återanvänder kod med komposition snarare än arv, vilket är något Docusaurus utnyttjar. Docusaurus och React är två delar som kommer vara omfattande i denna uppsats.
1.2 Problembeskrivning
Askås e-handelsplattform har ett API för att hantera kunder, ordrar och produkter som används av ett urval av Askås kunder i olika syften. För detta API har Askås ett verktyg som testar olika anrop som används av kunder och internt bland utvecklarna. Verktyget är förklarat som svårt att använda och lider av brist på dokumentation. Askås önskar få hjälp med att undersöka vad som utgör bra dokumentation för ett API-verktyg för att hjälpa till med förbättring av det verktyg som finns.
1.3 Syfte och mål
Askås för närvarande ligger i process att utveckla en ny webbsida som testar deras API med hjälp av Docusaurus, där målet är att sidan ska bestå av ett verktyg som är lättare att använda och förstå med hjälp av en medföljande dokumentation kring de anrop som verktyget har möjlighet att göra till API:t. I denna uppsats presenteras ett projekt utfört med React och Docusaurus där målet var att skapa ett verktyg som ska kunna testa ett befintligt API.
1.4 Etik och samhälle
Personlig hantering av data är något som alltid måste respekteras och är något som utvecklare förr eller senare kommer i kontakt med när det gäller API:n som kommuni- cerar med en databas. I det här projektet tilldelades en webbsida i demosyfte, samt en demonstrationssida för Askås nuvarande API-verktyg som speglar det som deras kunder förses med, som är kopplat till Askås databas. I detta verktyg är det bland annat möjligt att uppdatera information i saboteringssyfte för befintliga användare, men om det är kopplat till en nyskapad databas gjort för detta projekt eller den “riktiga” databasen, som är fylld med information om Askås kunder, är något som undgått kunskapsmässigt
1.5. METOD 7 i detta projekt då det inte har prövats.
1.5 Metod
I början av arbetet tilldelades ett demonstrationsverktyg som speglar en avgränsad ver- sion av det nuvarande verktyget. Med hjälp av denna tillsammans med möten kring projektet fastställdes en problembeskrivning för att lättare förstå vad målet är och hur detta ska uppnås. Utifrån detta undersöktes befintliga fältstudier, vetenskapliga artiklar, öppna API:er samt etablerade dokumentationsverktyg för att få en idé om hur analysen skulle påbörjas. För att bestämma en stadig grund för projektet hölls en kontinuerlig dialog med Askås under projektets gång i form av veckovisa möten, vilket bidrog till att projektet höll en tydlig riktning. En kontinuerlig dialog med handledarna på Askås och granskning av existerande litteratur kring ämnet gav projektet en bra utvecklingskurva.
Med de veckovisa mötena kunde Askås följa utvecklingen av projektet, fortlöpande utvärdera framgången och ge feed-back gällande eventuella justeringar. På grund av den rådande pandemin har hela projektet utförts på distans.
1.6 Fördelning av arbete
Båda parter har varit involverade i samtliga delar då projektet har utförts över Discord med dess skärmdelningsfunktion. På så sätt har skärmdelandet växlats mellan båda parterna där ena parten haft en granskande roll, medan den andre haft en praktisk roll. Målet har varit att växla mellan dessa roller på 50/50, dock har det stundtals varit humörbaserat sett till vem som tar vilken roll. Rent praktiskt har detta inneburit parprogrammering, men appliceras även på uppsatsskrivandet, där skrivandet har skett i samspel med varandra. På de möten som ägt rum med handledare på Askås har skärm- delning och förklaring av kod, tankar och idéer varit väldigt jämt fördelat.
1.7 Uppdragsgivare
Askås bedriver en e-handelsplatform som har utvecklats och modifierats i över 20 år och har cirka 300 kunder inom branscher som mode, hälsa, möbler, etc. Utöver e- handel integrerar även Askås betalningssystem, marknadsutrymmen och affärssystem som är relevanta till kundens behov. De beskriver att deras fokus ligger i att skapa smarta system som håller sig stabilt i takt med framtidens utveckling inom området.
Askås är ett expanderande företag och kommer i Augusti 2021 ha över 60 anställda som omfattar backend-utvecklare, frontend-utvecklare, supporttekniker och projektledare, samt kundansvariga säljare på marknadsavdelningen och administrativ personal. Dessa är utspridda över två kontor lokaliserade i Säffle och Karlstad, men har under pandemin gjort en omväxling till arbete hemifrån [10, 11, 12].
1.8 Avgränsningar
Tillsammans med Askås gjordes en initial avgränsning till endast en kategori av anrop till API:t för att minimera dubbelarbete, då kategorierna är ganska lika varandra. Denna avgränsning blev snabbt förlegad, vilket innebar att avgränsningen sattes till det avska- lade demonstrationsverktyg som tilldelades vid projektstart. Detta medförde att, från det demonstrationsverktyg som det fanns tillgång till, blev inget avgränsat i projektet.
1.9 Disposition
I kapitel 2 presenteras den problematik som finns gällande API-dokumentation baserat på den undersökning som gjorts av befintliga fältstudier och artiklar. Vidare förkla- ras utvecklingsmiljön för projektet och avslutas med en analys kring den förenämnda problematiken som ger underlag till viktiga riktlinjer för arbetet. Kapitel 3 inleds med instruktioner över den installation av paket och verktyg som behövdes för att realisera
1.9. DISPOSITION 9 arbetet, följt av tankegångar kring designen över både React och Docusaurus och hur detta implementerades. Kapitel 4 presenterar implementationen i sin helhet med alla respektive delar ihopkopplade. Här tas även begränsningar och problem som upplevdes och dök upp under projektets gång upp. Kapitel 5 avslutar uppsatsen med en diskussion kring arbetet och tar upp idéer som inte hunnits implementeras. Avslutningsvis finns en summering och några personliga reflektioner kring arbetet i helhet.
Kapitel 2 Bakgrund
Detta kapitel presenterar den bakomliggande undersökning kring API-dokumentation som lägger grunden för projektet, samt redogör för relevant bakgrundsinformation kring den utvalda utvecklingsmiljön för projektet. Som avslut framförs en analys baserat på undersökningen kring problematiken med API-dokumentation.
2.1 Webb-API
Ett Webb-API är ett definierat gränssnitt som tillåter kommunikation mellan webbsida och ändpunkt med lagrad data. Enligt den definierade specifikationen matar användaren in önskad information att få ut, och den bakomliggande koden för webbsidan gör ett anrop till en databas med en HTTP-begäran. I ett Webb-API finns även en specificerad struktur för hur svarsmeddelandet ska se ut, typiskt sett i XML (Extensible Markup Language)- eller JSON-format (JavaScript Object Notation). Ett API har ofta en central roll i ett företags tjänster för att exempelvis kunna söka upp material eller artiklar som ett företag erbjuder [13, 14]. Ett exempel på ett användningsområde är ett företag som erbjuder ett API till sina kunder som kartlägger vilka produkter som köps och ger rekommendationer på liknande produkter andra användare som köpt samma produkt
11
också köpt.
2.2 API-dokumentation
I denna sektion ges en förklaring av vad API-dokumentation är, varför det finns, och den vanligaste problematiken gällande dokumentering baserat på bakgrundsstudier pre- senteras även.
2.2.1 API-dokumentationens syfte
API-dokumentation ska ge en heltäckande överblick med hänsyn till vad en användare behöver veta av vad ett API erbjuder, hur det används och har syftet att öka förståelsen hos användaren, både ny som erfaren. För extern användning ger det användaren utökade möjligheter med API:t, medan för intern användning ger det inblick vid kundservice och felsökning, samt förenkling vid potentiella ändringar av API:t [13].
En utmaning för den som utvecklar ett API är att konstruera det på ett sådant sätt att det bör kunna hantera nya förändringar till tjänsten i syfte av att bättre betjäna sina användare [15]. Det gör det motiverande att den tillhörande dokumentationen också bör vara anpassningsbar.
En dokumentering som ökar förståelsen hos användaren förbättrar upplevelsen hos denne och skapar nöjdare kunder. Ju fler användare som finner värde i ett API, desto större anledning finns det att utöka API:ts tjänster och leder till att det finns större at- traktion för nya kunder. Dokumentering förminskar även tiden det tar för nya användare att anpassa sig till API:t, vilket leder till mindre tid för kundtjänst hos utvecklarna. Det förenklar även utvecklarnas arbete vid upprätthållning av tjänsten [5].
2.2. API-DOKUMENTATION 13
2.2.2 Problemen med API-dokumentation
I en studie från Robillard påstås att det största hindret gällande användandet av ett API brister i dokumenteringen [4]. Vidare har det undersökts (Robillard, DeLine, 2011) om andra problem som försvårar inlärningen av ett API. Denna studie betonar vikten i att skriva kod som är lätt att felsöka, och ska inte avslöja för mycket av API:ts interna element ur ett säkerhetsperspektiv. Vidare betonas att dokumentationen ska förklara avsikten hos ett API. Studien nämner även att dokumentationen skall skrivas på ett tilltalande sätt och skall innehålla exempel [16].
Det stämmer överens med en liknande studie från Meng, Steinhardt och Schubert.
Enligt denna letas det oftast först efter en generell överblick över vad API:t har möjlighet att göra vid presentation av ett nytt API. Användarna vill förstå hur och varför API:t används, men i undersökningen benämndes även att sådan information är av lite intresse, och menar att det viktigaste är att komma igång direkt för att få en visuell representation av vad API:t gör.
Enligt undersökningen är de vanligaste problemen gällande användandet av ett API att det brister i dokumenteringen. Det framgår att dokumentationen ofta är felaktig eller ofullständig och svår att förstå. Undersökningen visar även att det är vanligare att söka efter information på exempelvis Google eller Stack Overflow istället för att inspektera dokumentationen för API:t, eftersom dessa bland annat har tidsstämplar på när frågorna var ställda och tillåter kommentarer från flera användare [17, 18]. Ett problem med forskningen kring vad som utgör ett fullständigt dokumenterat API är att det inte är fullt förstått [17].
Gällande de tekniska bitarna bör parametrar, objekt och metoder vara förklarade utöver det som kan härledas ur namnen på dessa, men inte till den grad att det blir överväldigande. Vissa situationer kan även motivera en förklaring för vad som händer givet ett inmatat värde i en parameter [17].
2.3 React
I denna sektion ges en introduktion kring strukturen för React som gränssnitt med bakomliggande logik för hur detta uttrycker sig.
2.3.1 Introduktion till React
React är ett ramverk för JavaScript som är skapat av Facebook för att enklare kunna ska- pa interaktiva grafiska gränssnitt. I React kan man skapa komponenter som fungerar likt JavaScript-funktioner, men fungerar självständigt och returnerar HTML via en render- funktion [19]. Dessa kan anropas ett flertal gånger med olika inmatningar för att göra varje anrop unikt. Komponenter är uppdelade för olika ändamål och kan kombineras för att utöka komplexiteten. Till exempel kan en komponent hantera back-endlogik, och en komponent kan hantera utdata. Tillsammans eller enskilt kan man testa de komponenter som skapats genom att skapa en React-app som genererar en lokal webbsida som kan användas som testmiljö [20, 21].
Med en fetch-funktion kan en URL hämtas som React-komponenten kan interagera med för att göra ett API-anrop. Man skickar med lämpliga sidhuvuden och en brödtext som representerar parametrarna som ligger i källkoden för API:t. Detta konverteras se- dan till ett JSON-objekt och skickas iväg via en HTTP-begäran till servern och förväntas ett svar i form av ett JSON-objekt. React har möjligheten att binda data med hjälp av tillstånd och lyssnare. Tillstånd initialiseras med ett värde på varje komponent och ändras under dess livstidscykel[20, 21]. I figur 2.1 finns ett konkret exempel på hur en fetch fungerar. Det som har specificerats i detta anrop är vilken URL som informationen ligger på där svaret hämtas. Svaret från fetch-funktionen har tilldelats en variabel som konverterar svaret till ett JSON-objekt [20, 21].
2.3. REACT 15
Figur 2.1: En komponent som gör ett fetch-anrop vid knapptryck
2.3.2 Virtual-DOM
En webbsida består huvudsakligen av tre delar: innehåll, formgivning och logik, där HTML-kod motsvarar innehåll, CSS motsvarar formgivning och JavaScript motsvarar logik. React-ramverket ger möjligheten att kombinera innehåll och logik på ett effektivt sätt genom att använda sig av en Virtual-DOM (VDOM). En Document Object Model (DOM) representerar en webbsida i form av ett träd som skapas utifrån HTML-koden för sidan och delar upp de olika elementen som finns i koden [22]. Ett nytt träd måste genereras vid varje händelse som orsakas av en användare eller en server, men att generera ett nytt sådant vid varje händelse är ineffektivt och kräver mycket prestanda.
Den VDOM som React använder sig av är en abstrakt kopia av det riktiga DOM- trädet och saknar egenskapen att utföra någon egentlig förändring av webbsidan. När ett DOM-träd genereras skapar React sitt eget VDOM-träd. Vid varje interaktion skapar React sedan ett nytt VDOM-träd som jämförs med det äldre VDOM-trädet. Har det skett en förändring i det nya VDOM-trädet lagrar React den förändringen och uppdaterar
det riktiga DOM-trädet, avgränsat till enbart det som är nödvändigt att uppdatera [20].
Fördelen med VDOM är att det sänker tidskomplexiteten från O(n3) till O(n) där n motsvarar antal element i trädet [23].
2.3.3 Render
React-komponenter måste implementera en render-funktion som består av ett eller flera React-element och fastställer vad som ska visas på webbsidan. Ett React-element är den minsta byggstenen i en React-komponent och det är elementen i render-funktionen tillsammans med DOM:en som presenterar resultatet av komponenten. En fördel med React är att DOM:en uppdaterar enbart de element i render som behövs, det vill säga att den genererar inte om alla element utan enbart de som förändrats. Render-funktionen exekveras däremot inte hela tiden, då det krävs att antingen ett tillstånd ska ha föränd- rats, eller att komponenten ska ha anropats, för att komponenten ska exekvera sin render.
Figur 2.1 är exempel på när render först genererar text och en knapp för att sedan rendera en tabell, då ett tillstånd förändras när användaren trycker på knappen.
React har även stöd för att använda sig av JSX-syntax i render. JSX är forfarande JavaScript och passerar genom en JSX-kompilator innan exekvering, dock mer kortfat- tat. I figur 2.2 finns två komponenter som presenterar samma resultat, men de är skrivna i JSX respektive JavaScript. JSX kan även vara enklare för erfarna webbutvecklare då dess syntax är lik HTML och XML [24, 21, 25]. Som en fördel undanmanövrerar JSX inmatade värden som inte är specifikt definierande i applikationen som standard, och konverterar allt till en sträng innan rendering, vilket ger ett skydd mot XSS-attacker (cross-site scripting) [21].
2.4. MARKDOWN 17
Figur 2.2: Den övre figuren representerar JSX och den undre figuren JavaScript-kod
2.4 Markdown
Markdown är en filtyp för att underlätta dokumentering och göra den mer stilren. Det fungerar som ett alternativ till HTML men har inte fullt stöd för alla HTML-taggar.
Syftet med Markdown är däremot att det ska vara lätt att läsa och att lätt att skriva, se figur 2.3 för exempel på Markdown-kod. Fördelen med Markdown däremot är sin korthet i jämförelse med HTML, se figur 2.4 för HTML-kod [26].
Utöver Markdown finns MDX, som är en typ av Markdown-fil med stöd för JSX- syntax, vilket ger möjligheten att kombinera JSX-kod med vanlig Markdown-kod och få utökade funktioner. På grund av detta kan man importera React-komponenter direkt i Markdown [27].
Figur 2.3: Markdown-kod för sidan thank-you.md som genereras av Docusaurus vid skapande av en Docusaurus-sida
Figur 2.4: Samma sida som i figur 2.3 uttryckt i HTML-kod
2.5. DOCUSAURUS 19
2.5 Docusaurus
Docusaurus är ett projekt skapat av Facebook där tanken är att det ska gå att generera webbsidor snabbt och enkelt. Docusaurus stöttar integrering av React-komponenter med hjälp av Markdown-filer och skapar en webbsida vid kompilering där olika mallar finns att välja, men det går även att justera designen efter eget behag. Docusaurus har stöd för en mängd bibliotek och ramverk med funktioner som möjliggör att bland annat anpassa sitt användargränssnitt och implementera öppna API:er. Docusaurus har även stöd för MDX, vilket innebär att Markdown och JSX kan kombineras och på så sätt få ett upplägg där API-anrop som skapats i React kan implementeras i Docusaurus och ytter- ligare kompletteras med Markdown-funktionalitet, vilket ger möjlighet till fullständig dokumentation [28].
2.6 Node.js
Node.js är en öppen exekveringsmiljö med stöd för JavaScript som tillåter JavaScript- kod att exekveras utanför en webbläsare. På detta sätt kan JavaScript användas för att uppnå back-endfunktionalitet för en webbsida. Node.js undviker även en multi-trådad nätverksfunktion vilket gör att problemet med dödläge elimineras och anrop kan ske asynkront. Detta innebär att ett anrop inte är beroende av att tidigare anrop måste köra färdigt [29, 30].
2.7 Analys av problembeskrivning
I avsnitt 2.2.2 fastställs att vad som utgör en fulländad API-dokumentation inte är fullt förstådd, men att etablerade slutledningar finns. Det innebär att den dokumentation som blir framställd måste göras på ett sådant sätt att det är benäget för eventuella förändringar. Vid utvecklandet av dokumentation för ett befintligt API där använd-
ningsområdet består av kunder som besitter olika nivåer av kompetens är det motiverat att undersöka öppna API:er, då dessa bäst representerar en bred grad av användare [31]. Med undersökning av sådana och med de härledningarna som lyfts fram under sektion 2.2 kan ett antal punkter uppmanas att införa i dokumentationen som tillhör detta projekt:
• En teknisk beskrivning av vad API:t gör med avsikten för det bör presenteras.
• Nya punkter ska vara enkla att lägga till för att få dokumentationen dynamisk.
När detta senast uppdaterades bör vara tydligt för att användaren skall kunna se hur aktuell informationen är.
• Arkitekturen kring verktyget ska vara uppbyggd på ett sådant sätt att det ska vara enkelt att bläddra igenom API:ts tjänster i dokumentationsverktyget likt en bok.
Var inmatning sker och var utmatning hamnar ska presenteras på ett tydligt sätt.
• Kodexempel för generella anrop med beskrivande parametrar ska finnas tillgäng- liga. Det har funnits att ett längre exempel försvagar pedagogiken, medan ett kort exempel kan vara av för litet värde. Det bör även finnas fler än ett exempel och dessa ska vara så pass kompletta att det ska gå att kopiera och klistra in.
• Exempel bör utvecklas som demonstrerar bra praxis för användning av API:t över samtliga kategorier som innehåller anrop.
• Genomträngligheten måste begränsas då säkerhetsbrister inte är önskvärt. Här kommer nuvarande säkerhet att analyseras för förbättringar.
• Koden skall förklaras designmässigt för att förenkla vidarearbete.
Ovanstående lista kommer att agera riktlinje till det nya verktyget då dessa är punk- ter som anses vara de viktigaste i en tydlig och bra dokumentation [32, 16, 18, 13]. Se avsnitt 4.5 och avsnitt 5.2 för återkoppling.
Kapitel 3
Implementation
I detta kapitel fastställs installationen som krävdes för att kunna påbörja projektet.
Därefter följer en redogörelse av designval för det verktyg som utvecklades i projek- tet, tillsammans med tillvägagångssättet som denna design realiserades med hänsyn till både React och Docusaurus. Som avslut presenteras hur resultatet implementeras i Markdown.
3.1 Installation
I denna sektion förklaras vilken installation som måste göras för att kunna köra Re- act mot en lokal webbsida genererad av Docusaurus i utvecklingssyfte för att hantera webbsidans logik.
3.1.1 Node Package Manager och Yarn
För att ha möjlighet att använda React-ramverket behövs något för att kunna hantera JavaScript som back-end. Node package manager (NPM) är ett öppet mjukvaruregister som använder sig av Node.js för att kunna integrera bibliotek, ramverk och paket i ett projekt [33]. För att installera NPM behövs Node.js, som innehåller NPM och kan
21
laddas ned på NPM:s officiella hemsida. Med hjälp av NPM kan sedan Yarn installeras genom att skriva “npm install -g yarn” i kommandotolken/terminalen. Yarn är en pa- kethanterare som bygger på NPM och har utökad funktionalitet som uppnår snabbare exekveringstid än NPM [34]. Yarn är inte nödvändigt att använda men är behagligt på grund av dess snabbhet.
3.1.2 Npx och React-app
Ett paket som medföljer i Node.js och senare versioner av NPM (>= 5.2) är NPX, som tillåter kod som är byggd med Node.js att köras [30]. För att skapa en generell React- app skrivs “npx create-react-app my-app” där “my-app” kan ersättas med valfritt namn.
Med hjälp av detta skapades en testmiljö för att utöka kunskaperna om React.
3.1.3 Docusaurus-app
Docusaurus, förklarat i 2.5, kapslar de ovanstående ramverken för att generera en webb- sida med stöd för React och MDX. Docusaurus erbjuder diverse mallar för denna ge- nerering och installeras genom att mata in “npx @docusaurus/init@latest init [name]
[template]” i kommandotolken/terminalen, där “name” står för ett valfritt namn och
“template” den mall som väljs. De mallar som finns är classic, facebook och bootstrap.
I detta projekt används classic, som även rekommenderas av Docusaurus. Mallen in- nehåller ett ramverk för CSS-styling, dokumentation och struktur som enkelt kan redi- geras efter ändamål [28]. När sidan sedan är skapad hostas den på localhost:3000 med kommandot “yarn start”, som skrivs i kommandotolken/terminalen efter navigering till Docusaurus-projektet.
3.2. BEFINTLIGT VERKTYG 23
3.2 Befintligt verktyg
För att kunna bygga ett funktionellt anrop mot Askås server var det först nödvändigt att inspektera den demonstrationssida som tilldelades vid projektstart. Genom att göra ett direkt anrop från den går det att inspektera element för att se vad API:t förväntar, och hur svaret är uppbyggt. Genom detta sätt kunde förståelse för anropet byggas upp.
I figur 3.1 finns det befintliga verktyget med ett givet anrop men däremot inget svar, när användaren trycker på “Send” skickas förfrågan och svaret speglas i den högra rutan.
Figur 3.1: Det befintliga verktyget som används av Askås
3.3 Design
I denna sektion presenteras de designval som gjordes under projektets gång med både React och Docusaurus i åtanke, tillsammans med resonemang för projektets uppbygg- nad.
3.3.1 Principiell design
I sektion 2.7 fastställs de viktiga punkter som utgör målet med det nya verktyget, och utifrån dessa lades fokus på att skapa en universell komponent för att minimera arbetet som krävs för att lägga till stöd för nya anrop. Vidare kommer denna att kallas hu- vudkomponenten. Denna skall innehålla logik för ett anrop och vara designad på ett sådant sätt att oavsett vilket anrop som skickas till API:t skall komponenten hantera det på ett korrekt sätt. Detta leder till att information decentraliseras från React-delen av verktyget, vilket tydliggör strukturen över verktyget från en utvecklares perspektiv och tillåter en och samma komponent att sköta samtliga anrop.
3.3.2 Design React
Syftet med huvudkomponenten är att den skall ge användaren full kontroll över vilket anrop som skall skickas till API:t placerat på den bakomliggande servern med valfria parametrar på ett sätt som är tilltalande för såväl kund som utvecklare. Anropet ska pre- senteras i ett textfält som kan redigeras fritt, det är däremot viktigt att tänka på syntaxen för anropet då texten skall formateras till ett JSON-objekt. Det är innehållet i textfältet som kommer att skickas till servern via en “skicka”-knapp. React-komponenten skall då ta inmatningen givet av användaren, skicka till servern och spegla resultatet på sidan.
För att presentera detta smidigare skapades en hjälpkomponent som hanterar svaret från servern och visar upp det på sidan.
3.3. DESIGN 25
3.3.3 Design Docusaurus
Vid skapande av en Docusaurus-webbsida genereras ett grafiskt användargränssnitt. I figur 3.2 visas webbsidan som genereras med mallen classic. Vilken mall som används är oväsentligt i det här fallet då syftet med Docusaurus var att implementera React- komponenter för att få ett ramverk att arbeta inom och uppnå interaktion mellan Mark- down och React, samt en idé om hur resultatet kommer att se ut. En testmiljö, med andra ord. Eftersom Askås utnyttjar en egen Docusaurus-webbsida är val av mall relativt ointressant i detta arbete och inget vidare fokus lades i att utforska de andra mallarna.
Figur 3.2: Standardiserad design på ett Docusaurus-projekt med classic-mall
Det är viktigt att ta hänsyn till var React-komponenten skall placeras i mappstruktu- ren eftersom platsen måste definieras vid importeringen av anropsparametrarna. I figur 3.3 ses mappstrukturen för den Docusaurus-webbsida som finns i figur 3.2 då ingen ju- stering har skett. Logiken för startsidan hittas i src/pages/index.js. Alla Markdown-filer placerades sedan i docs, och React-komponenter placerades godtyckligt i “src/pages”.
Figur 3.3: Mappstruktur på ett Docusaurus-projekt med classic-mall vid namn my- website
Skapandet av element i navigeringsmenyn sker i “docusaurus.config.js”, där en kopp- ling till en given mapp görs. För att skapa ett “sidebar-element” i en navigeringsflik info-
gas detta i “sidebars.js” där valfri namngivning sker. Denna sätts samman i docusaurus.config.js.
I figuren 3.4 syns att webbsidan innehåller en navigeringsmeny med ett fåtal alternativ.
Syftet, designmässigt, är att API-anropen skall importeras i Markdown-filer som ligger under ett menyalternativ. Detta görs genom att placera strängar i Markdown som de- finierar en korrekt anropsstruktur som React-komponenten använder sig av, och sedan anropa denna.
3.4. UTVECKLING AV HUVUDKOMPONENTEN 27
Figur 3.4: Hur urvalet av olika API-anrop presenteras
3.4 Utveckling av huvudkomponenten
I den här sektionen förklaras den funktionalitet som utgör den grund som huvudkompo- nenten består av.
3.4.1 Anropet
Fetch är en funktion som kan hämta lagrad data på en hemsida och returnera ett svar [21]. I figur 3.5 ses en funktion som heter getperson. Den hämtar den data som finns på hemsidan “https://jsonplaceholder.typicode.com/users/1”, och i det här fallet finns det fakta om en exempelperson i JSON-format. Svaret från fetch-metoden sparas undan i konstanten response. Viktigt att notera är att det står “await” efter response och content - detta för att programmet inte skall fortsätta exekvera förrän svaret har sparats undan korrekt till response. Detsamma gäller när funktionen skall konvertera JSON-objektet till hanterbar data i content.
Figur 3.5: Det första anropet som gjordes under utvecklingen av komponenten
Figur 3.6 är render-funktionen till anropet ovan i figur 3.5. Eftersom render-funktionen
inte har tillgång till content då denna variabel ligger lokalt i getperson betyder det att getperson måste uppdatera tillståndet data. Data i det här fallet är avsett för att lagra värdet av svaret från fetch och i samband med att getperson använder setState-metoden körs render-funktionen på nytt. Getperson uppdaterar även tillståndet dataLoaded och sätter den till sant vilket betyder att när render körs kommer den att returnera en titel och två spalter med det namn och mejladress personen associerad till anropet har. Figur 3.7 är resultatet av render-funktionen före och efter användaren tryckt på “Get a person”.
Figur 3.6: Render-funktionen som renderar en knapp om dataLoaded är false, annars skrivs resultatet ut
Figur 3.7: Utseende före respektive efter knapptryck
3.4. UTVECKLING AV HUVUDKOMPONENTEN 29
3.4.2 Forma ett anrop
Det finns möjligheter att utveckla fetch-anropet som ses i figur 3.8. Det går att speci- ficera vilken “method” som skall användas, vilka anropshuvud (eng: headers) som ska skickas med och vad brödtexten (eng: body) ska innehålla. Det är i brödtexten som användaren kan specificera ett anrop och i figur 3.8 skickas variabeln “request” med som brödtext.
Figur 3.8: Exempel på parametrar som fetch kan använda sig av
Ett API-anrop kommunicerar med en bakomliggande programkod vilket gör att det som skickas in måste innehålla viss information och ha korrekt struktur för att kunna tas emot som ett godtyckligt anrop av API:t. Detta läses in som en sträng ur en Markdown- fil som komponenten omvandlar till ett JSON-objekt och läggs i ett tillstånd vid namn request. Detta tillstånd placeras i en “textarea” som ett standardvärde vid rendering av webbsidan vilket gör att användaren enkelt kan redigera anropet givet ett korrekt format.
I figur 3.9 ges ett exempel på ett ping-anrop som är fördefinierat och fungerar som en mall för ett visst anrop. Mallen placeras i en textarea, och som figuren visar är inte anropet skickat till servern ännu. Användaren har då möjligheten att skicka detta anrop till servern eller förändra innehållet i textarean efter behag. Notera att innehållet på texten är viktig att bibehålla för att få ett korrekt svar då det utgör syntaxen för anropet, som är vitalt för att lyckas formatera om texten till ett JSON-objekt. Vilka parametrar som i huvudsak påverkar anropet skall förklaras i den dokumentation som ska tillhöra varje anrop. Det som framför allt skiljer anropen är de parametrar som finns under
“params”.
Figur 3.9: En textarea som innehåller ett exempel på ett ping-anrop
3.4.3 Händelser
När en användare förändrar innehållet i textarean aktiveras en händelse (eng: event).
Händelsen leder till att en funktion anropas som skall hantera förändringen och spara undan den aktuella texten till tillståndet request. Figur 3.10 visar funktionen som han- terar detta. Event, som är funktionens parameter, är hela texten som finns i textarean. I variabeln “text” sparas det inlästa värdet från textarean, som har ett standardiserat värde som motsvarar ett anrop enligt den struktur som förväntas. Detta konverteras till ett JSON-objekt och läggs i den globala förfrågan som skickas till servern. I det globala tillståndet “Sent” indikeras det om det aktuella anropet som finns i textarean inte har skickats, vilket förändras då användaren skickar anropet.
3.5. DOKUMENTATION 31
Figur 3.10: Funktionen som anropas då en förändring i textarean sker
3.5 Dokumentation
Fokus i dokumenteringen var att den ska var tydlig och kort - den får inte vara överflödig men bör ändå vara tydlig i vad som gör vad och vad som krävs för att få ett godtyckligt svar. Detta gäller även svaret från servern som ska presenteras tydligt och stilrent. För att kunna presentera svaret från servern används tillståndet “response”, som lagrar det JSON-objekt som servern returnerar, demonstrerat i figur 3.11.
Figur 3.11: Hur svaret sparas undan
Det textfältet som presenterar resultatet går inte att justera utan det är för att läsa enbart. Fältet är däremot dynamiskt och är beroende av svaret från servern. I figur 3.9 finns ett ping-anrop som kan skickas till servern, och i figur 3.12 finns svaret av detta
anropet där “ping” skickas in med “Hello!” och får tillbaka samma meddelande från
“pong”. Utöver ett tydligt anrop och svar finns det stöd för dokumentation som förklarar anropet. Den anges vid implementeringen av komponenten tillsammans med mallen för anropet i MDX-format. Dokumentation skall vara en förklarande del av anropet med en tydlig och kort text om anropet tillsammans med vilka parametrar som är obligatoriska och vad de innebär. Dokumentationen skall presenteras i form av en tabell på begäran av Askås.
Figur 3.12: Svaret som ges av ett ping-anrop
I figur 3.13 finns en version av den dokumentation som skall förklara vilka para- metrar som är viktiga i anropet samt en kort förklaring av anropet och vilket svar det ska resultera i. Syftet är att dokumentationen skall presenteras före anropet för att göra anropet tydligt innan användaren testar anropet.
3.6. INTERAKTION MELLAN MARKDOWN OCH REACT 33
Figur 3.13: Tabell för viktiga parametrar i ping-anropet
3.6 Interaktion mellan Markdown och React
Docusaurus har ett utvecklat stöd för React-komponenter vilket gör det enkelt att imple- mentera dem i Docusaurus. Det enda som krävs är att starta upp en egen Docusaurus- webbsida, skapa en Markdown-fil (eller använda dem som genereras automatiskt av Docusaurus vid installation) och importera komponenten. Figur 3.14 illustrerar hur React-komponenter importerar i MDX där “MainComponent” är namnet på den React- komponenten som exporteras från filen med samma namn.
Figur 3.14: Hur man implementerar en React-komponent i MDX
I sektion 3.5 visas hur komponenter kan interagera med tillstånd och “props”. På samma sätt sker denna interaktion mellan MDX-filerna som motsvarar de olika API- anropen och huvudkomponenten. I figur 3.15 syns den data som ligger standardiserat i textarean i Ping-anropet, demonstrerat i figur 3.9 samt 3.12. MDX-filerna är fyllda med strängar som huvudkomponenten kommer åt med “this.props.data” och “this.props.docs”
och konverterar till JSON-objekt för att kunna godtas av servern vilket figur 3.16 illu- strerar. I konstruktorn för huvudkomponenten skapas ett globalt tillstånd som läser in de props som “docs” och “data” innehåller i MDX-filen i “documentation” och “request”.
Eftersom dessa är strängar görs de om till JSON-objekt och vidarehanteras som sådana.
Figur 3.15: Fälten som passeras från en MDX-fil till React-komponenterna
Figur 3.16: Konstruktorn för huvudkomponenten
3.7. DOKUMENTATIONSKOMPONENTEN 35
3.7 Dokumentationskomponenten
För att dynamiskt kunna dokumentera viktiga parametrar justeras “fields” i figur 3.15 genom att lägga till eller ta bort en “param”. Detta skickas vidare till en “dokumenta- tionskomponent” som itererar över alla fält och presenterar parametrarna i en dynamisk tabell. Figur 3.17 visar den bakomliggande koden för detta. Funktionen fieldsLoop tar in “fields” som en parameter, vilket den får inskickad som en “prop” från den MDX-fil som gjort ett anrop och lägger resultatet i en global vektor. Detta används sedan för att rendera en tabell i funktionen renderTableData som anpassar tabellen till den storlek som den behöver ha.
Figur 3.17: Koden for komponenten som presenterar dokumenteringen av anropet
Kapitel 4 Resultat
I detta kapitel presenteras det resultat som uppnåddes i projektet i form av figurer, kod och diagram. Vidare tas även de begränsningar som erfors, och begränsningar som upplevdes under projektets gång upp.
4.1 Projektstruktur
Under den här sektionen finnes strukturen för projektets arkitektur, samt ett diagram som beskriver hur React-komponenterna är kopplade till de olika anropen.
4.1.1 Arkitektur
I figur 4.1 finns strukturen över det slutgiltiga verktyget innan det har exporterats till Askås. Under “pages” som i sin tur ligger i “src” befinner sig alla nödvändiga JSX-filer som behövs för att göra ett anrop, presentera ett anrop samt hantera dokumentationen.
Det finns även ett fåtal CSS-filer som sköter designen på webbsidan. Utöver JSX-filerna finns det åtta stycken MDX-filer under mappen “Dokumentation”, och det är i dessa som implementationen av “MainComponent” görs. Strukturen på MDX-filerna ger klarhet över de olika anrop som finns och vilka anrop som ligger i respektive MDX-fil. I dessa
37
finns de “tabitems” placerade som illustreras i figur 3.4. Det leder till att den textsträng som skickas till huvudkomponenten med tillhörande dokumentationssträng är beroende av vilken flik som trycks på.
Figur 4.1: Strukturen för det nya verktyget
4.1.2 UML-diagram
För att ge en bild över hur MainComponent används i MDX-filerna gjordes ett UML- diagram, se figur 4.2. Till vänster i figur finns alla MDX-filer, där struktur för utse- ende finns, samt strängarna som definierar den förklarande dokumentationen och de definierade anropen som renderas i MainComponent. Vidare passerar MainComponent
4.2. SLUTGILTIG VERSION 39 docs till Documentation, som renderar en tabell innehållandes de viktiga parametrarna för anropet tillsammans med en förklaring. I appkey ligger nycklar definierade som hashGen använder sig av. Dessa nycklar blir tilldelade individuellt och måste finnas för att få ett svar som inte ger ett felmeddelande från API:t.
Figur 4.2: UML-diagram för den slutgiltiga versionen
4.2 Slutgiltig version
I figurerna 4.3 och 4.4 finns den slutgiltiga resultatet och i det här fallet anropet “Get article”. I figur 4.3 finns sidofältet som presenterar alla kategorier av anrop som finns
implementerade i verktyget och under dessa kategorier finns det totalt 46 anrop.
Figur 4.3: Sidofältet för verktyget
I figur 4.4 finns en menystruktur innehållandes fyra alternativ, där exempelvis “Get article calls” i sin tur har sex stycken alternativ för olika anrop. Detta för att förtydliga strukturen över vilka olika kategorier som finns och vilka anrop som de tillhör då dessa flikar genererar olika texter i den stora textrutan.
Under menystrukturen finns det dokumenterat vad anropet gör med en kort för- klaring av de obligatoriska parametrarna. Under dokumenteringen ligger textrutan där användaren är försedd med en mall för hur ett anrop enligt “Get article” ser ut som denne är fri att redigera. Som beskrivningen av anropet säger är det “product_id” som är det mest relevanta i detta anrop. Användaren matar då in det produkt-ID denne önskar söka efter och trycker på “Generera hash”-knappen som gör att hashen i textrutan ändras automatiskt. Det går även att redigera detta fält manuellt om det, ur en utvecklares perspektiv, är intressant att se vad som returneras då en felaktig hash skickas. Genom att trycka på “Skicka” presenteras ett svar i rutan där det står “Svaret här”.
4.2. SLUTGILTIG VERSION 41
Figur 4.4: Anropet Get article från det nya verktyget
Figurerna nedan visar det bakomliggande koden som hanterar logiken i huvud- komponenten. Figur 4.5 visar konstruktorn för huvudkomponenten. De tillstånd som skapas här kan ses som globala variabler. Vidare visar figur 4.6 funktionerna som hu- vudkomponenten innehåller. Notera att hashGen-funktionen inte är medtagen i figuren på grund av säkerhetsskäl. Slutligen i figur 4.7 finns render, som ansvarar för placering av designmaterial och händelser och kommunicerar direkt med DOM:en.
Figur 4.5: Konstruktor för huvudkomponenten
4.2. SLUTGILTIG VERSION 43
Figur 4.6: Funktioner för huvudkomponenten
Figur 4.7: Render för huvudkomponenten
4.3 Begränsningar
I denna sektion presenteras de begränsningar som upplevdes i projektet och hur de hanterades för att fortsätta projektets utveckling.
4.3.1 Projektet
Till en början begränsades projektet till enbart till 15 olika anrop tillsammans med handledarna på Askås, då det till en början verkade som en rimlig avgränsning för att ge mer tid till utvecklingen av de komponenter som verktyget skulle använda sig av. Detta förblev däremot ingen begränsning när projektet avrundades eftersom att det blev lika lätt att lägga till ett anrop som 46 anrop på grund av huvudkomponenten konstruerades. På så sätt uppfyller det nya verktyget samma funktionalitet som det demonstrationsverktyg som projektet skulle baseras på.
4.3.2 Docusaurus
Ur ett designperspektiv förblev Docusaurus en begränsning då formatet som Docusaurus presenterar innehållet inom Markdown-filer är fördefinierat. Detta leder till att mycket hamnar centralt på webbsidan. Får det inte plats placeras det godtyckligt vertikalt, vilket gör att det blir mycket innehåll centralt på webbsidan som då innebär att användaren måste scrolla mycket för att se resterande information kontra en mer horisontell place- ring av presenterande text.
4.4 Problem
I den här sektionen presenteras de främsta problem som uppstod under projektets gång.
4.5. UTVÄRDERING 45
4.4.1 CORS
Cross Origin Resource Sharing (CORS) är ett protokoll som tillåter skript att köras från en klients webbläsare för att interagera med resurser från ett annat ursprung och triggas bland annat av fetch-begäranden [35]. JavaScript som standard tillåter inte resurser att hämtas från andra sidor av säkerhetsskäl [36]. I detta fall skickas begäranden till en annan domän som gör anrop till back-enddelen av API:t som CORS-protokollet initialt blockerade, vilket innebar att anropet inte gick igenom, något som var förbryllande.
Detta löstes genom att Askås fick lägga till en header på back-enden som tillät CORS för det nya verktyget.
4.4.2 Hashfunktionen
Ett anrop tar en del av datan ur anropet och genererar en sträng som går igenom en hashfunktion innan det skickas iväg till API:t. Hur denna funktion skapar en hash skiljer sig mellan olika anrop och kunde leda till att hashen blev felaktig, vilket innebar ett felmeddelande som retur från servern. För att se hur API:t godkände en hashsträng gavs åtkomst till den ansvarande koden för detta. Efter inspektering av denna kod kunde slutsatsen dras att en sortering för ett givet fält var nödvändig - något som följaktligen kunde implementeras i “MainComponent”.
4.5 Utvärdering
Utifrån den analys som fastställdes i kapitel 2.7 tillsammans med Askås, finns det en lösning till följande punkter:
• Nya punkter ska vara enkla att lägga till för att få dokumentationen dynamisk.
När detta senast uppdaterades bör vara tydligt för att användaren skall kunna se hur aktuell informationen är.
Lösning: Det är enkelt att justera anropen och dokumenteringen på grund av komponentens dynamiska aspekt. Markdown är tacksamt i den mening att det är enkelt att lägga till och ta bort innehåll. Dokumentationen är inte komplett i dagsläget och vidarebefordras till Askås utvecklare då de har större inblick i vad API:t gör. Däremot finns dokumentationskomponenten och MDX-filerna som ett skelett som enkelt kan utbyggas.
• Arkitekturen kring verktyget ska vara uppbyggd på ett sådant sätt att det ska vara enkelt att bläddra igenom API:ts tjänster i dokumentationsverktyget likt en bok.
Var inmatning sker och var utmatning hamnar ska tydliggöras.
Lösning:Eftersom det är samma huvudkomponent som används till alla anrop ger det stor igenkänningsfaktor, detta tillsammans med en tydlig struktur över de olika kategorier som finns tillsammans med en meny för att dela upp kategorierna i underkategorier. Kategorierna tydliggör vilket anrop som är inläst och är enkla att navigera kring.
• Kodexempel för generella anrop med beskrivande parametrar ska finnas tillgäng- liga. Det har funnits att ett längre exempel försvagar pedagogiken, medan ett kort exempel kan vara av för litet värde. Det bör även finnas fler än ett exempel och dessa ska vara så pass kompletta att det ska gå att kopiera och klistra in.
Lösning:Genom att fördefiniera ett anrop är strukturen redan klar och det krävs enbart mindre justeringar i anropet för att förändra det. Dokumentationen bidrar med en förtydligande text om vilka parametrar som är viktiga och vad som för- väntas som svar utifrån ett givet anrop. Svaret kan även bidra med eventuella felmeddelanden.
• Genomträngligheten måste begränsas då säkerhetsbrister inte är önskvärt. Här kommer nuvarande säkerhet att analyseras för förbättringar.
Lösning:Det fanns tyvärr varken tid eller tillgång till detta, men rekommenda-
4.5. UTVÄRDERING 47 tioner till förbättringar meddelades. Uppdaterade hashfunktioner och bättre han- tering av “appkey” är några förslag till en ökad säkerhet. Däremot bör noteras att en övergång till React är en säkerhetsförbättring i sig.
• Koden skall förklaras designmässigt för att förenkla vidarearbete.
Lösning:Koden har kontinuerligt kommenterats och verktyget tillsammans med koden kommer att demonstreras i realtid för Askås.
Sammanfattningsvis går det att konstatera att det nya verktyget har en lösning till de flesta punkter i ovanstående lista och har uppnått den målsättning som sattes vid projektstart. Det faktum att verktyget till stor del består av en React-komponent under- lättade mycket. På så vis minskar dubbelarbetet då ett nytt anrop ska läggas till och alla anrop delar struktur vilket gör dem väldigt lika samtidigt som det går att skapa unika anrop med tillhörande beskrivning.
Kapitel 5 Slutsats
Det här kapitlet tar upp en diskussion kring resultatet, hur vägen dit sett ut och vilka lärdomar det har givit. Potentiellt vidarearbete redogörs för, följt av en slutgiltig sum- mering av hela projektet samt personliga reflektioner.
5.1 Diskussion
Några av de största webbsidorna i världen använder sig av React-ramverket, vilket ger en indikation till dess popularitet. Att skapa komponenter som är återanvändbara visar sig vara en uppskattad utövning hos utvecklare och i stora företag. Det ger en högre prestanda och kvalité både i webbsidan och i koden.
Genom att genomföra ett projekt i JavaScript med fokus på React ger ett försprång i ett yrkesliv där väldigt mycket är Webb-baserat och det bara blir mer där React förmod- ligen kommer spela en stor roll i framtiden. Det nya verktyget har en tydligare struktur jämfört med det gamla med märkbart bättre prestanda. Det har även ett underliggande skelett i sin struktur som innebär att det kommer att vara enkelt att fortsätta arbetet och utöka dokumentationen för API:t.
49
5.2 Fortsatt arbete
Initialt kommer vidare arbete att innebära infogning av verktyget till den sida som utvecklas av Askås. Det fortsatta arbetet kommer även att implicera en integrering av de anrop som dokumentationsverktyget ska ha stöd för till sidan som benämns ovan.
Förslagvis kommer en “syntax highlighter” att implementeras för att markera att texten är i JSON-format. Askås får rekommendationen att byta ut den underliggande hashfunktionen till en mer robust funktion och att infoga ett exempelanrop som visar användaren hur ett korrekt anrop följt av ett substantiellt svar ser ut. Jämfört med andra liknande verktyg kan ett val mellan JSON och XML-format infogas. Vidare rekommen- deras att skapa en tillhörande sektion som ger en överblick om API:t och dess funktioner i enlighet med beskrivningen under sektion 2.2. Utöver den dokumentation som finns bör Askås även konstruera användarscenarion över API:t som demonstrerar hur det kan användas i dokumentationsverktyget.
5.3 Summering
Målet med projektet var att studera det befintliga verktyget och utveckla detta i form av ett nytt verktyg skrivet i JavaScript, med hjälp av React, för att sedan implementera detta i Docusaurus. Askås var intresserade av en bättre API-dokumentation, då det befintliga beskrevs svåranvänt och dåligt dokumenterat. Projektet skulle bli en del av deras nya dokumentationsverktyg, vilket gav det hela en ny dimension.
Handledarna från Askås har agerat vägledare under projektet för att uppnå det mål som efterfrågats ur ett praktiskt perspektiv. Arbetet började med en undersökning för att underlätta utvecklingen av projektet samtidigt som det fanns mycket att lära. Askås gav tips och idéer om var utvecklingen skulle börja och mellan de veckovisa möten som fanns sattes det upp mindre mål som skulle uppnås och utvärderas, vilket ledde till en större förståelse kring helheten. Med en ökad förståelse kring React kunde me-
5.4. PERSONLIGA REFLEKTIONER 51 ningsfulla API-anrop skapas, som slutligen kunde integreras i Docusaurus. Med den kunskapen kunde en dynamisk React-komponent skapas som kunde stå för logiken i anropen, och som kunde anpassa sig till det anrop som skulle skickas. På liknande sätt kunde en dokumentationskomponent skapas, som var en viktig del i projektet. Dessa, ihopkopplade med olika MDX-filer som skickar in information om anropet beroende på vad som tryckts på, ledde till ett slutgiltigt dokumentationsverktyg. Totalt har detta verktyg stöd för 46 olika anrop, vilket är en avgränsning då dessa 46 endast är de anrop som demonstrationssidan som tilldelades vid projektstart innehöll. Med hänsyn till att det finns fler anrop utöver dessa var det nödvändigt med en generell lösning som resulterade i ett förminskande av dubbelarbete för vidare implementering i framtiden gällande Askås egna användning av detta projekt. I lösningen var det även viktigt att ta hänsyn till hur det bakomliggande API:t är uppbyggt, då parametrarna inte går igenom hur som helst.
5.4 Personliga reflektioner
Arbetet har varit ett givande sätt för oss att lära oss JavaScript tillsammans med ett populärt gränssnitt som React. Med hänvisning till undersökningen i kapitel 1.1 är det lätt att se varför så många utvecklare vill jobba med React - det är smidigt, finns bra dokumentation och det är kul att få feedback på koden direkt i form av en front- endkopplad webbsida. Däremot tog det lite tid att komma in i det då ingen av oss tidigare har jobbat med JavaScript, men vi tycker att det gav utdelning på det sätt att vi fick erfarenhet av “full stack”-arbete, det vill säga att vi fick arbeta med både front- end och back-end.
Något som var förvånande för oss var hur enkelt det var att integrera React-komponenter i Markdown. Det gjorde att vi kunde gå långt över den initiala avgränsningen som sattes i början av projektet - att verktyget endast skulle ha stöd för samtliga artikelanrop. Detta
gör att Askås enkelt kan bygga vidare på de komponenter vi har utvecklat genom att bara skriva en Markdown-fil med det anrop som ska stödjas. Projektet har givit en inblick i hur en dag ser ut på Askås kontor och framför allt hur arbetslivet ser ut inom detta område och vikten av att känna till JavaScript och React. En intressant aspekt till detta arbete är att det verktyg som utvecklats är något som kommer att komma till nytta och användas, vilket är en stor anledning till varför vi var intresserade av detta projekt.
Litteratur
[1] eBay Developers Program. Accessed: 2021-05-05.URL: https://developer.
ebay.com/common/api?mkevt=1&mkcid=1&mkrid=711- 53200- 19255-0&campid=5337590774&customid=&toolid=10001.
[2] Art Anthony. Tracking the Growth of the API Economy: Nordic APIs. Accessed 2021-05-05. April 2016. URL: https://nordicapis.com/tracking- the- growth-of-the-api-economy/.
[3] Santos Wendell. APIs show Faster Growth Rate in 2019 than Previous Years.
Accessed 2021-04-28. Juli 2019. URL: https : / / www . programmableweb . com / news / apis - show - faster - growth - rate - 2019 - previous - years / research/2019/07/17.
[4] Martin P Robillard. “What makes APIs hard to learn? Answers from developers”.
I: IEEE software 26.6 (2009), s. 27–34.
[5] Vasudevan Keshav. What Is API Documentation, and Why It Matters? Accessed 2021-02-19. Juni 2017.URL: https://swagger.io/blog/api-documentation/
what-is-api-documentation-and-why-it-matters/.
[6] Stack Overflow Developer Survey 2020. Accessed: 2021-04-29. URL: https : //insights.stackoverflow.com/survey/2020.
[7] Danillo Corvalan, Doel Sengupta och Manu Singhal. Getting Started with React.
Packt Publishing, 2016.
53
[8] Built With. React Usage Statistics. Accessed 2021-04-28.URL: https://trends.
builtwith.com/javascript/React.
[9] John Otander m. fl. Markdown for the component era. Accessed 2021-04-29.
URL: https://mdxjs.com/.
[10] Välkommen till oss på Askås. Accessed: 2021-03-18. URL: https : / / www . askas.se/sv/om-askas.html.
[11] Askås 20 years of e-commerce experience. Accessed: 2021-03-18.URL: https:
//www.kau.se/index.php/en/cs/news/askas-20-years-e-commerce- experience.
[12] Askås storsatsar anställer helt fotbollslag". Accessed: 2021-03-18.URL: https:
//www.askas.se/sv/nyheter-fran-askas/askas-anstaller-elva-nya- medarbetare.html.
[13] Application programming interface. Accessed: 2021-03-25.URL: https://en.
wikipedia . org / wiki / Application _ programming _ interface ? oldid = 673710319 & fbclid = IwAR18d6dM6BHVR13U0Lw0z66Wc5kEvIVWQFQqq _ 6K - Z1X1G_VEeXQ24cOwUg.
[14] C Rudrakshi m. fl. API-fication-core building block of the digital enterprise. Tekn.
rapport. Technical report, HCL Technologies, 2014.URL: https://www.hcltech.
com/sites/default/files/apis_for_dsi.pdf.
[15] Vasudevan Keshav. The Path to a Successful API. Accessed 2021-02-18. Nov.
2016. URL: https : / / swagger . io / blog / api - strategy / building - a - successful-api/.
[16] Martin P Robillard och Robert DeLine. “A field study of API learning obstacles”.
I: Empirical Software Engineering 16.6 (2011), s. 703–732.
LITTERATUR 55 [17] Michael Meng, Stephanie Steinhardt och Andreas Schubert. “Application pro- gramming interface documentation: what do software developers want?” I: Jour- nal of Technical Writing and Communication 48.3 (2018), s. 295–330.
[18] Qiang Fan m. fl. “Why API documentation is insufficient for developers: an em- pirical study”. I: Science China Information Sciences 64.1 (2021), s. 1–3.
[19] W3schools. React Components. Accessed 2021-02-25. URL: https : / / www . w3schools.com/react/react_components.asp.
[20] Artemij Fedosejev. React.js essentials. Packt Publishing Ltd, 2015.
[21] React - A JavaScript library for building user interfaces. Accessed: 2021-02-18.
2021.URL: https://reactjs.org.
[22] Web technology for developers. Accessed: 2021-02-19.URL: https://developer.
mozilla.org/en-US/docs/Web/API/Document_Object_Model.
[23] Reconciliation. Accessed: 2021-02-19. URL: https : / / reactjs . org / docs / reconciliation.html.
[24] Cory Gackenheimer. Introduction to React. Apress, 2015.
[25] Rendering Elements. Accessed 2021-02-18. URL: https : / / reactjs . org / docs/rendering-elements.html#gatsby-focus-wrapper.
[26] Jens Voegler, Jens Bornschein och Gerhard Weber. “Markdown–A simple syntax for transcription of accessible study materials”. I: International Conference on Computers for Handicapped Persons. Springer. 2014, s. 545–548.
[27] Using React. Accessed: 2021-02-27. URL: https://docusaurus.io/docs/
markdown-features/react.
[28] Build optimized websites quickly, focus on your content: Docusaurus. Accessed:
2021-01-29.URL: https://docusaurus.io/.
[29] Node.js. About Node.js. Accessed: 2021-01-29.URL: https://nodejs.org/
en/about/.
[30] Introduction to Node.js. Accessed: 2021-01-29. URL: https://nodejs.dev/
learn.
[31] Robert B Watson. “Development and application of a heuristic to assess trends in API documentation”. I: Proceedings of the 30th ACM international conference on Design of communication. 2012, s. 295–302.
[32] Michael Meng, Stephanie M Steinhardt och Andreas Schubert. “Optimizing API Documentation: Some Guidelines and Effects”. I: Proceedings of the 38th ACM International Conference on Design of Communication. Department of Business Studies and Information Sciences, Merseburg University of Applied Sciences, Merseburg, Germany. 2020, s. 1–11.
[33] About npm. Accessed: 2021-02-14. URL: https://docs.npmjs.com/about- npm.
[34] Yarnpkg. 1 - Introduction. Accessed: 2021-02-14. URL: https : / / yarnpkg . com/getting-started.
[35] Fetch. Accessed: 2021-03-05. April 2021.URL: https://fetch.spec.whatwg.
org/.
[36] Steve Hobbs. What is CORS? Complete Tutorial on Cross-Origin Resource Sha- ring. Accessed: 2021-03-05. April 2019. URL: https : / / auth0 . com / blog / cors-tutorial-a-guide-to-cross-origin-resource-sharing/.
