OpenAPI Specifications

This directory contains the API documentation for the Wallet (as of this writing 2025-10-21, specifically, the disclosure API for the verification_server’s public and private endpoints, and the issuance_server’s issuance and disclosure-based issuance endpoints).

There are a couple of documents here:

• wallet-components.openapi.yaml: An OpenAPIv3 components library which are used by our API specification documents below (you shouldn’t open this in a Swagger/OpenAPI editor/preview on its own);

• wallet-disclosure-private.openapi.yaml: The private/internal API for the verification_server’s disclosure functionality;

• wallet-disclosure-public.openapi.yaml: The public/external API for the verification_server’s disclosure functionality;

• wallet-issuance.openapi.yaml: The API for the issuance_server’s issuance and disclosure-based issuance functionality;

You can open these OpenAPIv3 documents using Swagger UI and/or some facility in your favorite editor (like Postman, or Redocly in Jetbrains editors which comes as a part of the OpenAPI (Swagger) Editor Plugin).

To serve the OpenAPI specifications using a Swagger UI docker container:

cd nl-wallet
docker run --name swagger --detach --rm -p 8080:8080 \
-e URLS='[ { url: "openapi/wallet-disclosure-private.openapi.yaml", name: "Disclosure Private (requester) API" }, { url: "openapi/wallet-disclosure-public.openapi.yaml", name: "Disclosure Public (wallet) API" },  { url: "openapi/wallet-issuance.openapi.yaml", name: "Issuer API" } ]' \
-e URLS_PRIMARY_NAME='Disclosure Private (requester) API' \
-v "$(pwd)/wallet_docs/openapi":/usr/share/nginx/html/openapi \
swaggerapi/swagger-ui

Then visit http://localhost:8080. The above docker invocation executes the container in the background. To see the output of the docker container, you can run docker logs -f swagger. To stop the container (and remove it because we specified --rm), you can run docker stop swagger.