Merge pull request #65 from c4dt/add_swagger

Adding documentation to DPPTConfigController

Makefile

@@ -0,0 +1,41 @@
+######################
+#      Makefile      #
+######################
+
+FILE_NAME = documentation.tex
+
+LATEX = xelatex
+BIBER = biber
+RUSTY_SWAGGER = rusty-swagger
+
+all: clean all1
+all1: clean updateproject updatedoc swagger la la2 la3 
+no: clean updateproject updatedoc swagger la la2 
+docker-build: updateproject docker
+doc: updatedoc swagger la la2 la3
+
+updateproject:
+	mvn -f dpppt-config-backend/pom.xml install
+
+updatedoc:
+	mvn -f dpppt-config-backend/pom.xml install -Dmaven.test.skip=true
+	mvn springboot-swagger-3:springboot-swagger-3 -f dpppt-config-backend/pom.xml
+	mkdir -p documentation/yaml
+	cp dpppt-config-backend/generated/swagger/swagger.yaml documentation/yaml/sdk.yaml
+
+swagger:
+	cd documentation; $(RUSTY_SWAGGER) --file ../dpppt-config-backend/dpppt-config-backend/generated/swagger/swagger.yaml
+
+la:
+	cd documentation;$(LATEX) $(FILE_NAME)
+bib:
+	cd documentation;$(BIBER) $(FILE_NAME)
+la2:
+	cd documentation;$(LATEX) $(FILE_NAME)
+la3:
+	cd documentation;$(LATEX) $(FILE_NAME)
+show:
+	cd documentation; open $(FILE_NAME).pdf &
+
+clean:
+	@rm -f documentation/*.log documentation/*.aux documentation/*.dvi documentation/*.ps documentation/*.blg documentation/*.bbl documentation/*.out documentation/*.bcf documentation/*.run.xml documentation/*.fdb_latexmk documentation/*.fls documentation/*.toc

README.md

@@ -1,2 +1,46 @@
 # dp3t-config-backend-ch
 
+This backend is used by the apps to get their config every 6h. It is used by the Swiss Government to update the 
+epidemiological parameters if needed.
+
+The following endpoints are available:
+
+- `/v1` - returns `Hello from DP3T Config WS`
+- `/v1/config` - returns a `ConfigResponse` with the following structure and default values:
+  - `InfoBoxCollection` - empty by default
+    - `deInfoBox` `InfoBox`
+      - `title` `String`
+      - `msg` `String`
+      - `url` `String`
+      - `urlTitle` `String`
+      - `isDismissible = false`
+    - `frInfoBox` `InfoBox`
+    - `itInfoBox` `InfoBox`
+    - `enInfoBox` `InfoBox`
+    - `ptInfoBox` `InfoBox`
+    - `esInfoBox` `InfoBox`
+    - `sqInfoBox` `InfoBox`
+    - `bsInfoBox` `InfoBox`
+    - `hrInfoBox` `InfoBox`
+    - `srInfoBox` `InfoBox`
+    - `rmInfoBox` `InfoBox`
+  - `SDKConfig` - will soon be removed (30/7/2020)
+    - `numberOfWindowsForExposure = 3`
+    - @Deprecated `eventThreshold = 0.8f`
+    - @Deprecated `badAttenuationThreshold = 73.0f`
+    - `contactAttenuationThreshold = 73.0f`
+  - iOSGaenSdkConfig `GAENSDKConfig`
+    - `lowerThreshold = 53`
+    - `higherThreshold = 60`
+    - `factorLow = 1.0d`
+    - `factorHigh = 0.5d`
+    - `triggerThreshold = 15`
+  - androidGaenSdkConfig `GAENSDKConfig`
+- `/v1/testinfobox/config` - returns a `ConfigResponse` with only the `SDKConfig` set to a static message
+
+## /config special actions
+
+The call to `/v1/config` does the following special actions:
+1. `If iOS == 13.6`: warn that the German 'no risk' message is misleading
+1. `If App == Testflight`: warn that the app should be updated to the official app-store app
+1. `If App == Initial iOS test app`: set `factorHigh` = `0` to avoid errors

documentation/yaml/sdk.yaml

@@ -0,0 +1,198 @@
+openapi: 3.0.0
+servers:
+- url: https://demo.dpppt.org
+  description: ''
+info:
+  version: 1.0-gapple
+  description: DP3T API
+  title: DP3T API
+paths:
+  /v1/:
+    get:
+      summary: hello
+      description: Echo endpoint
+      responses:
+        '200':
+          description: Hello from DP3T Config WS
+          content:
+            application/json:
+              schema:
+                type: string
+  /v1/config:
+    get:
+      summary: getConfig
+      description: Read latest configuration and messages, depending on the version
+        of the phone and the app.
+      responses:
+        '200':
+          description: ConfigResponse structure with eventual notifications and epidemic
+            parameters
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.ConfigResponse'
+      parameters:
+      - name: osversion
+        in: query
+        description: Version of the OS
+        example: ios13.6
+        required: true
+        schema:
+          type: string
+      - name: buildnr
+        in: query
+        description: Build number of the app
+        example: ios-200619.2333.175
+        required: true
+        schema:
+          type: string
+  /v1/testinfobox/config:
+    get:
+      summary: getGhettoboxConfig
+      description: getGhettoboxConfig
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.ConfigResponse'
+      parameters:
+      - name: appversion
+        in: query
+        description: ''
+        required: true
+        schema:
+          type: string
+      - name: osversion
+        in: query
+        description: ''
+        required: true
+        schema:
+          type: string
+      - name: buildnr
+        in: query
+        description: ''
+        required: true
+        schema:
+          type: string
+components:
+  schemas:
+    org.dpppt.switzerland.backend.sdk.config.ws.model.ConfigResponse:
+      type: object
+      properties:
+        forceUpdate:
+          type: boolean
+        forceTraceShutdown:
+          type: boolean
+        infoBox:
+          $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.InfoBoxCollection'
+          description: Holds a message translated in different languages
+          example: ''
+        sdkConfig:
+          $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.SDKConfig'
+          description: Configuration of the epidemiological parameters for the pre-GAEN
+            DPPPT process
+          example: ''
+        iOSGaenSdkConfig:
+          $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.GAENSDKConfig'
+          description: GAEN epidemiological parameters for iOS
+          example: ''
+        androidGaenSdkConfig:
+          $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.GAENSDKConfig'
+          description: GAEN epidemiological parameters for Android
+          example: ''
+    org.dpppt.switzerland.backend.sdk.config.ws.model.GAENSDKConfig:
+      type: object
+      properties:
+        lowerThreshold:
+          type: integer
+          description: Lower threshold that is sent to the GAEN to count encounters
+            with other devices. It is expressed in dB attenuation from the Bluetooth
+            chip.
+          example: '53'
+        higherThreshold:
+          type: integer
+          description: Higher threshold that is sent to the GAEN to count encounters
+            with other devices It is expressed in dB attenuation from the Bluetooth
+            chip.
+          example: ''
+        factorLow:
+          type: number
+          format: double
+          description: Multiplication factor used to weigh the return value of the
+            GAEN in attenuationDuration[0]
+          example: 1.0d
+        factorHigh:
+          type: number
+          format: double
+          description: Multiplication factor used to weigh the return value of the
+            GAEN in attenuationDuration[1]
+          example: 0.5d
+        triggerThreshold:
+          type: integer
+          description: Minimum duration of exposure in minutes, before an encounter
+            is added to the attenuationDuration
+          example: '15'
+    org.dpppt.switzerland.backend.sdk.config.ws.model.InfoBox:
+      type: object
+      properties:
+        title:
+          type: string
+          description: Title of the infobox
+          example: Alert
+        msg:
+          type: string
+          description: Message shown to the user
+          example: Please restart your phone
+        url:
+          type: string
+          description: If given, adds a url to the message
+          example: https://dp-3t.github.io/
+        urlTitle:
+          type: string
+          description: Title to be shown for the URL
+          example: DP3T page
+        isDismissible:
+          type: boolean
+          description: If true, the user can cancel the message
+          example: 'true'
+    org.dpppt.switzerland.backend.sdk.config.ws.model.InfoBoxCollection:
+      type: object
+      properties:
+        deInfoBox:
+          $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.InfoBox'
+        frInfoBox:
+          $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.InfoBox'
+        itInfoBox:
+          $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.InfoBox'
+        enInfoBox:
+          $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.InfoBox'
+        ptInfoBox:
+          $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.InfoBox'
+        esInfoBox:
+          $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.InfoBox'
+        sqInfoBox:
+          $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.InfoBox'
+        bsInfoBox:
+          $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.InfoBox'
+        hrInfoBox:
+          $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.InfoBox'
+        srInfoBox:
+          $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.InfoBox'
+        rmInfoBox:
+          $ref: '#/components/schemas/org.dpppt.switzerland.backend.sdk.config.ws.model.InfoBox'
+    org.dpppt.switzerland.backend.sdk.config.ws.model.SDKConfig:
+      type: object
+      properties:
+        numberOfWindowsForExposure:
+          type: integer
+        eventThreshold:
+          type: number
+          format: float
+        badAttenuationThreshold:
+          type: number
+          format: float
+        contactAttenuationThreshold:
+          type: number
+          format: float

dpppt-config-backend/.gitignore

@@ -0,0 +1,2 @@
+generated
+target

dpppt-config-backend/pom.xml

@@ -29,6 +29,12 @@
     </properties>
 
     <dependencies>
+        <dependency>
+            <groupId>ch.ubique.openapi</groupId>
+            <artifactId>doc-annotations</artifactId>
+            <version>1.0.1</version>
+        </dependency>
+
         <dependency>
             <groupId>org.springframework</groupId>
             <artifactId>spring-context</artifactId>
@@ -170,8 +176,27 @@
                 <enabled>true</enabled>
             </snapshots>
         </repository>
+        <repository>
+            <snapshots>
+                <enabled>false</enabled>
+            </snapshots>
+            <id>ubique-oss-springboot-swagger3</id>
+            <name>bintray</name>
+            <url>https://dl.bintray.com/ubique-oss/springboot-swagger3</url>
+        </repository>
     </repositories>
 
+    <pluginRepositories>
+        <pluginRepository>
+            <snapshots>
+                <enabled>false</enabled>
+            </snapshots>
+            <id>ubique-oss-springboot-swagger3</id>
+            <name>bintray</name>
+            <url>https://dl.bintray.com/ubique-oss/springboot-swagger3</url>
+        </pluginRepository>
+    </pluginRepositories>
+
     <build>
         <finalName>
 			dpppt-config-backend
@@ -198,6 +223,9 @@
                 <configuration>
                     <source>${java-version}</source>
                     <target>${java-version}</target>
+                    <compilerArgs>
+                        <arg>-parameters</arg>
+                    </compilerArgs>
                 </configuration>
             </plugin>
             <!--reproducible builds -->
@@ -260,6 +288,32 @@
 				  </execution>
 				</executions>
 			  </plugin>
+
+            <plugin>
+                <groupId>ch.ubique.openapi</groupId>
+                <artifactId>springboot-swagger-3</artifactId>
+                <version>1.2.8</version>
+                <configuration>
+                    <apiVersion>1.0-gapple</apiVersion>
+                    <basePackages>
+                        org.dpppt.switzerland.backend.sdk.config.ws.model
+                    </basePackages>
+                    <blackListedPackages>
+                        <blackListedPackage>com.google.protobuf</blackListedPackage>
+                    </blackListedPackages>
+                    <ignoredTypes>
+                        <ignoredType>byte</ignoredType>
+                    </ignoredTypes>
+                    <controllers>
+                        <controller>org.dpppt.switzerland.backend.sdk.config.ws.controller.DPPPTConfigController</controller>
+                    </controllers>
+                    <description>DP3T API</description>
+                    <apiUrls>
+                        <apiUrl>https://demo.dpppt.org</apiUrl>
+                    </apiUrls>
+                    <title>DP3T API</title>
+                </configuration>
+            </plugin>
 <!--            <plugin>-->
 <!--                <groupId>org.jacoco</groupId>-->
 <!--                <artifactId>jacoco-maven-plugin</artifactId>-->