Documentation

Every software project includes a set of architecture decisions defining boundaries and constraints for further design and implementation. It’s important to document those decisions somehow or else a development team might not know which decisions where made and with which assumptions. Or they know the decision but are missing the context and the consequences and therefore decisions are blindly accepted or blindly changed. In the following short tutorial I will show how to structure architecture decisions in so called Architecture Decision Records and how to manage them with a simple tool named ADR-Tools. ...

Maintaining architecture rules and constraints for a specific software project or an application is not easy as textual documentation is easily forgotten after a while and hard to verify. ArchUnit is a testing library that allows developers and software architects to write down such rules as executable tests that may be run by the development teams and the integration servers. In the following article I will demonstrate the basic features of this library by applying rules and constraints to an existing application. ...

Spring Boot allows us to create RESTful web-services with ease, Swagger specifies a format to describe the capabilities and operations of these services and with Swagger UI it is possible to explore our REST API with a nice graphical user interface in our browser. Springfox is a project that aims at creating automated JSON API documentation for API’s built with Spring and is used in the following tutorial to integrate Swagger into a sample application. ...

A variety of different tools exists to help us analyze RESTful web-services and create documentations for their APIs in different formats. In the following tutorial I’d like to demonstrate how to document an existing JAX-RS web-service in multiple formats like Swagger, AsciiDoc or Plain Text using Maven, the JAX-RS Analyzer and the JAX-RS Analyzer Maven Plugin. The JAX-RS Analyzer gathers its information not only by reflection like most other tools but also by bytecode analysis and therefore does not require us to add special annotations for documentation to our code. ...

Generate AsciiDoc Documentation and Publish it with GitLab Pages We setup a repository and add a directory named docs there .. this is the home of our AsciiDoc files. We’re using asciidoctor/docker-asciidoctor as Docker image for tool provisioning This is the .gitlab-ci.yml, we’re running the stage only when something in the docs directory has changed. stages: - "Build docs" # The name of the job activates the GitLab pages publication pages: image: asciidoctor/docker-asciidoctor stage: "Build docs" tags: - build script: - sh ./gen_docs.sh - mv output public only: refs: - master changes: - /docs/* artifacts: paths: - public expose_as: 'Documentation Archive' ...