arc42.org-site VS swagger-ui

There a various standards for documenting software architecture, like arc42 or C4. While useful and somewhat well-known (there is certainly a correlation here), here architecture documentation can be further simplified, particularly due to the self-similarity of project and component. Following is a small template, that can also serve as a project's and component's README:

I've been using https://structurizr.com/ to automatically generate C4 diagrams from a model (rather than drawing them by hand). It works well with the approach for written documentation as proposed in https://arc42.org/. It's very easy to embed a C4 diagram into a markdown document.

The result is a set of documents and diagrams under version control that can be rendered using the structurizr documentation server (for interactive diagrams and indexed search).

I also use https://d2lang.com/ for declarative diagrams in addition to C4, e.g., sequence diagrams and https://adr.github.io/ for architectural decision records. These are also well integrated into structurizr.

My general approach to documentation is a "software guidebook" (free e-book link) or arc42 ... complemented with diagrams and architecture decision records where necessary.

In addition to a small number of diagrams, I'd recommend something like arc42 or my "software guidebook" (link for a free copy of my book describing this), plus some architecture decision records.

Arc42 may give some inspiration https://arc42.org/

If you need more structure than ADRs then https://arc42.org is super useful.

There are plenty of good resources out there for learning modeling languages and architectural documentation structures. For more lightweight methods, I'd recommend checking out resources like Simon Brown's C4 model for visualizing software architecture, Martin Fowler's UML Distilled: A Brief Guide to the Standard Object Modeling Language, Scott Ambler's Agile Modeling site, and the arc42 template for architectural documentation.

As you need to, you can get into topics like different modeling languages or documentation template libraries. These are going to be highly dependent on your organization, though, as different organizations have different standards for what and how to document design decisions. Personally, I've found that the arc42 documentation template plus the C4 modeling language plus the UML modeling language (see UML as sketch and UML as notes for more on lightweight UML) for the most detailed models (which are rarely needed outside of the most complex parts of a system) tends to be a good, agile, lightweight model for the kinds of things to think about when it comes to creating design documentation.

We've started using Arc42 and C4 model & PlantUML for diagrams. Working out well so far.

arc42 - arc42

Swagger is a fantastic open-source toolset that's perfect for developing and describing RESTful APIs. It offers you a user-friendly interface to understand a service's capabilities without needing to dig into the code. It even provides a way for you to interact directly with the API, which means you get to test its functionality.

The API had an OpenAPI endpoint built with Swagger where I could download a JSON specification file for the API.

Swagger is a widely used tool for documenting and testing APIs.

Swagger is an open-source software framework that implements the OpenAPI Specification—an API description format for REST APIs. The OpenAPI Specification defines a standard, language-agnostic interface to HTTP APIs, enabling both humans and computers to discover and understand the capabilities of the API.

Mocking and Testing: Once the API design is complete, developers create mock APIs to simulate the behavior of the actual services. This early testing phase helps identify any issues or mismatches between design and implementation before substantial development efforts are invested. Tools like Postman or Swagger are invaluable for API testing and validation.

import fp from "fastify-plugin"; import swagger from "@fastify/swagger"; export default fp(async (fastify) => { fastify.register(swagger, { openapi: { info: { tags: [ { name: "drinks", description: "Drink-related endpoints", externalDocs: { description: "Find out more", url: "http://swagger.io", }, }, ], }, }, }); });

A very requested feature for Sharkio was the auto-generation of OpenAPI documentation using the recorded HTTP requests - to create standardized documentation.

Automation QA is a lot of the same duties as manual QA, but instead of writing and executing the test plans manually, we create and update automated tests that can run those validations programmatically, for example by using Selenium to automatically fill out and submit forms for a web application, or using Postman and/or Swagger to generate an API conversation test.