WPB-6177 document steps for creating new API version

changelog.d/4-docs/WPB-6177

@@ -0,0 +1 @@
+Documentation for creating a new API version updated

docs/src/developer/developer/api-versioning.md

@@ -107,15 +107,20 @@ non-overlapping version ranges.
 
 When making the client API version bump, i.e., when finalising a version, there
 are several steps to make apart from deciding what endpoint changes are part of
-the version:
-
- - In `wire-api` extend the `Version` type with a new version by appending the
-   new version to the end, e.g., by adding `V6`.
- - In the same `Version` module update the `developmentVersions` value to list
-   only the new version,
- - Consider updating the `backendApiVersion` value in Stern, which is
-   unit-tested by checking if it is listed as supported in the response to `GET
-   /api-version`.
+the version. In these example we assume that version `V6` should be finalized and `V7` should be created:
+
+- Run wire-server and download the `swagger.json` of the current development version, e.g. with the following command: `curl localhost:8080/v6/api/swagger.json | jq > swagger-v6.json` and copy the file to `services/brig/docs/swagger-v6.json`.
+- In `wire-api` extend the `Version` type with a new version by appending the
+  new version to the end.
+- In the same `Version` module update the `developmentVersions` value to list
+  only the new version.
+- In `services/brig/src/Brig/API/Public.hs`
+  - update `versionedSwaggerDocsAPI` so that the finalized version points to the pregenerated swagger
+  - and `internalEndpointsSwaggerDocsAPI` so that the finalized version `V6`, the new version `V7`, as well as the unversioned path point to the swagger of the internal API, and the previous latest stable version V5 points to an empty swagger.
+- Set the version for `gDefaultAPIVersion` in `integration/test/Testlib/Env.hs` to 7.
+- Consider updating the `backendApiVersion` value in Stern, which is
+  unit-tested by checking if it is listed as supported in the response to `GET
+  /api-version`.
 
 ### Examples of endpoint evolution
 

services/brig/src/Brig/API/Public.hs

@@ -197,12 +197,12 @@ versionedSwaggerDocsAPI (Just (VersionNumber V6)) =
       & S.info . S.description ?~ $(embedText =<< makeRelativeToProject "docs/swagger.md")
       & S.servers .~ [S.Server ("/" <> toUrlPiece V6) Nothing mempty]
       & cleanupSwagger
-versionedSwaggerDocsAPI (Just (VersionNumber V0)) = swaggerPregenUIServer $(pregenSwagger V0)
-versionedSwaggerDocsAPI (Just (VersionNumber V1)) = swaggerPregenUIServer $(pregenSwagger V1)
-versionedSwaggerDocsAPI (Just (VersionNumber V2)) = swaggerPregenUIServer $(pregenSwagger V2)
-versionedSwaggerDocsAPI (Just (VersionNumber V3)) = swaggerPregenUIServer $(pregenSwagger V3)
-versionedSwaggerDocsAPI (Just (VersionNumber V4)) = swaggerPregenUIServer $(pregenSwagger V4)
 versionedSwaggerDocsAPI (Just (VersionNumber V5)) = swaggerPregenUIServer $(pregenSwagger V5)
+versionedSwaggerDocsAPI (Just (VersionNumber V4)) = swaggerPregenUIServer $(pregenSwagger V4)
+versionedSwaggerDocsAPI (Just (VersionNumber V3)) = swaggerPregenUIServer $(pregenSwagger V3)
+versionedSwaggerDocsAPI (Just (VersionNumber V2)) = swaggerPregenUIServer $(pregenSwagger V2)
+versionedSwaggerDocsAPI (Just (VersionNumber V1)) = swaggerPregenUIServer $(pregenSwagger V1)
+versionedSwaggerDocsAPI (Just (VersionNumber V0)) = swaggerPregenUIServer $(pregenSwagger V0)
 versionedSwaggerDocsAPI Nothing = allroutes (throwError listAllVersionsResp)
   where
     allroutes ::
@@ -250,15 +250,11 @@ internalEndpointsSwaggerDocsAPI service examplePort swagger (Just (VersionNumber
     swagger
       & adjustSwaggerForInternalEndpoint service examplePort
       & cleanupSwagger
-internalEndpointsSwaggerDocsAPI service examplePort swagger (Just (VersionNumber V4)) =
-  swaggerSchemaUIServer $
-    swagger
-      & adjustSwaggerForInternalEndpoint service examplePort
-      & cleanupSwagger
-internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V0)) = emptySwagger
-internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V1)) = emptySwagger
-internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V2)) = emptySwagger
+internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V4)) = emptySwagger
 internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V3)) = emptySwagger
+internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V2)) = emptySwagger
+internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V1)) = emptySwagger
+internalEndpointsSwaggerDocsAPI _ _ _ (Just (VersionNumber V0)) = emptySwagger
 internalEndpointsSwaggerDocsAPI service examplePort swagger Nothing =
   internalEndpointsSwaggerDocsAPI service examplePort swagger (Just maxBound)
 

services/brig/src/Brig/API/Public/Swagger.hs

@@ -127,7 +127,7 @@ emptySwagger =
   swaggerSchemaUIServer $
     mempty @S.OpenApi
       & S.info . S.description
-        ?~ "There is no Swagger documentation for this version. Please refer to v3 or later."
+        ?~ "There is no Swagger documentation for this version. Please refer to v5 or later."
 
 {- FUTUREWORK(fisx): there are a few things that need to be fixed before this schema collection
    is of any practical use!