Hej och välkommen till repot för dokumentationen av Fysiksektionens hemsida! Här försöker vi hålla allt som är relevant för dig som ska utveckla på hemsidan. Repot innehåller:
- API-dokumentation
- Server för grafiskt interface av API:t
- Övrig dokumentation som ska flyttas till front- respektive backend
Fysiksektionens hemsida är starkt uppdelad mellan frontend och backend. För att dessa två delar ska kunna interagera har vi definierat ett API, som en gemensam överenskommelse. Detta API har och kommer fortsätta utvecklas tack vare idéer från både front- och backenden.
För att kunna dokumentera API:t på ett smidigt sätt så använder vi oss av standarden OpenAPI 3. Detta innebär att dkoumentationen består av json-filerna som finns under api-docs. Dessutom finns ett grafiskt interface baserat på SwaggerUI i form av en enklare React-app. Med hjälp av denna enkla app går det att läsa API:t på ett enkelt sätt, och det grafiska fungerar också som en debugger för filerna genom att visa felmeddelanden när det finns syntax-fel.
-
För att installera React-appen, se till att du har
nodeinstallerat. Om inte kan du finna nedladdningen här: Download NodeJS. Vi rekommenderar node 16.2.0. -
Navigera till api-server-mappen och kör:
npm install. Om du får varningar för paket vars versioner inte är kompatibla så bör du köranpm install --force, det är för att SwaggerUI har en något utdaterad React-komponent.
Kör npm run start-all från mappen api-server. När detta kommando har kört igång kör både React-servern och en liten server som levererar API-filerna. Därefter är det bara att använda menyn för att navigera API:t.
OpenAPI är ett projekt som har skapat en syntax för att dokumentera API:er på ett sätt så att både människor och datorer kan läsa det ganska enkelt. OpenAPI-världen tillsammans med ex. Swagger gör att det går att definiera, fakea, testa och visualizera sina API:er.
För att lära dig skriva API finns framförallt två resurser som rekommenderas: OpenAPI-Specification och även de filer som redan finns.