Lägga till OpenAPI-resurs

Owned by Andreas Carlsson (Unlicensed)
Last updated: Feb 08, 2022
1 min read

Enligt DIGG:s allmänna krav på REST API:er skall tjänstens OpenAPI-dokumentation exponeras enligt följande:

“Om OpenAPI dokumentationen återfinns online SKALL den vara en del av tjänsten under  /<api>/<tjänst>/v<x>/api-docs “.

Denna guide visar hur man åstadkommer detta i våra tjänster.

Quarkus-tjänster

För Quarkus-tjänster behöver följande göras:

  1. Lägg till följande attribut i application.properties:

    # Set OpenAPI-path quarkus.smallrye-openapi.path=/api-docs

  2. Skapa denna fil: /src/main/resources/META-INF/openapi.yaml

  3. Lägg till nedanstående innehåll i filen:

    paths: /api-docs: get: tags: - API summary: OpenAPI-definition parameters: [] x-auth-type: None responses: '200': description: ok

  4. Detta kommer att addera en ny resurs i tjänstens API. Resursen kommer att merge:as ihop med tjänstens befintliga API. Du behöver dock inte implementera någon logik för detta.

    Du når den genererade dokumentationen genom att köra:

    $ mvn clean compile quarkus:dev

    När tjänsten startat går du in på: https://localhost:8080/api-docs

    Den genererade OpenAPI-dokumentationen kan sedan användas för att uppdatera API:et i WSO2 på vanligt vis.

    När du uppdaterat API:et i WSO2 kommer en ny resurs att finnas tillgänglig. resursen kommer att ha autentiseringen avslagen. Detta innebär att man inte behöver vara autentiserad för att komma åt tjänstens OpenAPI-dokumentation.
    Exempel: https://api.sundsvall.se/disturbances/1.1/api-docs

Spring-Boot-tjänster

Se Bas-starter (dept44-starter) | openapi