Bas-starter (dept44-starter)

Bas-startern bör användas av alla utvecklade tjänster och den innehåller funktionalitet och konfiguration för:

• Felhantering

• RequestId-hantering

• Truststore

• Miljövariabel-hantering

• Loggning

• Jackson (serialisering/deserialisering av JSON och YAML)

• OpenAPI och Swagger UI

För att förenkla användning inaktiverar startern följande Spring Boot-auto-konfigurationer:

• org.springframework.boot.autoconfigure.security.servlet.UserDetailsServiceAutoConfiguration

• org.springframework.boot.autoconfigure.web.servlet.error.ErrorMvcAutoConfiguration

• org.zalando.problem.spring.web.autoconfigure.security.ProblemSecurityAutoConfiguration

Felhantering

Se Felhantering

RequestId-hantering

TODO

Truststore

Truststore-funktionalitet innebär att man kan skapa en “in-memory”-truststore baserat på SSL-certifikat (i PEM-format). Detta eliminerar behovet av att skapa separata truststore-/keystore filer med hjälp av t.ex. keytool. Det enda som behövs är att lägga certifikatet i katalogen classpath:truststore/.

Truststore används även av “spring-cloud-config-server-client”-funktionaliteten. I det fallet har även ett certifikat till “config-servern” bundlats med dept44-startern. Behovet av att varje klient måste sätta upp en egen truststore-fil för config-serverns SSL-cert är därmed undanröjt.

Miljövariabel-hantering

För att underlätta extern (läs: ej versionshanterad) hantering av credentials finns möjligheten att lägga till dessa som miljövariabler i en fil med namnet “.env”.

Filen skall ligga i classpath-rooten (t.ex. i projekt-rooten).

Det går att lägga till variabler på två olika sätt:

Med hjälp av SpringBoots teminologi

Exempel:

.env

example.variable=Hello World

application.properties får inte innehålla variabel med samma namn (eftersom property-filen har högre rang än env-filen)

#example.variable=Goodbye World <- denna måste tas bort eller kommenteras ut

I exemplet ovan kommer example.variable att ha värdet ‘Hello World’ när applikationen startar.

Med hjälp av spring-dotenv:s teminologi

Exempel:

.env

EXAMPLE_VARIABLE=Hello World

Variabeln kan sedan användas i applikationen.

application.properties:

example.name = ${env.EXAMPLE_VARIABLE:}

Mer information: https://github.com/paulschwarz/spring-dotenv

Loggning

Generell loggning sker med hjälp av SLF4J, t.ex.:

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
...
public class MyClass {
    private static final Logger LOG = LoggerFactory.getLogger(MyClass.class);
    ...

    public void doSomething(String s) {
        LOG.debug("Doing something with {}", s);
    }
}

Loggning av trafik, såväl för inkommande och utgående requests och responses sker med hjälp av biblioteket Logbook.

Inställningar
(Auto-konfigurationsklass: se.sundsvall.dept44.configuration.LogbookConfiguration)

Viktigt att komma ihåg om man sätter om logg-kategorin är att man då även sätter om loggnivån på den konfigurerade loggkategorin till TRACE - om det inte görs kommer ingen trafikloggning att dyka upp i applikationens logg.

Jackson (serialisering/deserialisering av JSON och YAML)

Jackson används för serialisering av objekt till JSON och tillbaka - d.v.s. deserialisering av JSON till objekt. Konfigurationen som görs i ramverket innefattar bland annat:

• null-värden exkluderas vid serialisering

• den JSON-data som genereras är indenterad, för ökad läsbarhet

• okända attribut ignoreras vid deserialisering

Vidare används Jackson för serialisering av objekt till YAML och tillbaka.

Inställningar
(Auto-konfigurationsklass: se.sundsvall.dept44.configuration.ObjectMapperConfiguration)

OpenAPI och Swagger UI

För att generera OpenAPI v3.x-specifikation och tillhandahålla ett Swagger UI används SpringDoc.

Minimal konfiguration i application.properties:

openapi.name=ett-api
openapi.title=Ett API
openapi.version=1.0

OpenAPI-specifikationen exponeras på /api-docs. Som standard serveras OpenAPI-specifikationen som JSON, med kan även fås som YAML genom att sätta Accept-headern till application/yaml. YAML-representation av OpenAPI-specifikationen kan även nås via /api-docs.yaml.

Vidare läggs en endpoint /api-docs till i tjänstens Swagger UI som kommer att vara åtkomlig utan autentisering, där man kan hämta OpenAPI-specifikationen.

Se nedan för övriga valbara inställningar.

Inställningar

(Auto-konfiguration: se.sundsvall.dept44.configuration.openapi.OpenApiConfiguration)