LIPPU-project API -definitions
This repository has the LIPPU-project API-definitions in Swagger 2.0 yaml-format.
You can build a Docker-environment to view the API-definitions
or you can open the
yaml/api.yml file in Swagger-editor.
Main documentation is located in the docs-folder.
To run the Swagger Docker container in local environment, run the following command (you must have Docker and Docker compose installed):
If you have used previously Swagger-UI docker image, be sure to use recent enough Docker image that have fixes for composed classes. If Docker throws an error about firewall blocking volume shares (common problem in the Windows environment), you must open ports for Docker in the firewall. See Docker's documentation for instructions.
It takes a while to build the containers and start them, so be patient :)
After the containers have started, open a browser and point it to the http://localhost address
to see the documentation. You can terminate the containers with
What's in the containers?
docker-compose up command is executed, the following will happen
- A Swagger UI container is created, which sees the
yaml/api.yml-file. Making a page reload will update the UI with the changes to the API-definitions.
- Another container is created, which has a stub implementation of the API. When the container is created, the code
is generated from the
yaml/api.ymlfile. The stub implementation will not update without restarting the container (see below).
- A Nginx-server is started, which acts as a forward-proxy for the previous two containers and provides them the same hostname, so you can access both containers from the developers machine.
You can use Swagger codegen-tool to build stub implementation for LIPPU API. The code and the documentation is available in the swagger-codegen Github-project and some examples are in the code generation section of the documents-file.
If you want to develop the API, it is recommended to start the Docker containers with the following docker-compose command:
docker-compose up --build
This will trigger Docker to rebuild images that have changes. The maven dependencies
used by the stub image are shared with the host OS using volume-directivies. This
way dependencies wont end up being part of the container and they are not
fetched everytime the container is built. These dependencies are stored in
directory. Building the containers for the first time takes time due
to the dependencies, but is faster the following times. When started,
the process will generate new stub implementation codes based on the
API-definitions, compile the code with maven and start the application
In the future the
docker-compose up command could start a reference implementation
of the API instead of the generated stub implementation. It could also replace the whole
Swagger UI container, as the reference implementation could provide the Swagger UI for the API.
This work is licended under EUPL (European Union Public Licence) version 1.2. See LICENSE.txt for more information.