Articles Tagged ‘documentation’

Managing Architecture Decision Records with ADR-Tools

Sunday, May 27th, 2018

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.

(more…)

Assuring Architectural Rules with ArchUnit

Monday, July 3rd, 2017

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.

(more…)

Integrating Swagger into a Spring Boot RESTful Webservice with Springfox

Wednesday, July 1st, 2015

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.

(more…)

Documenting RESTful Webservices in Swagger, AsciiDoc and Plain Text with Maven and the JAX-RS Analyzer

Tuesday, June 16th, 2015

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.

(more…)

Search
Tags
Categories