Our great sponsors
-
swagger-ui
Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
-
-
SurveyJS
Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.
-
Defining and documenting API can be a challenging task. Fortunately, we have something called a swagger — a set of open-source tools built around the OpenAPI Specification that can help you design, build, document, and consume REST APIs. Thanks to them, you can create a webpage with all endpoints defined with their query params, body params, schemas of the expected response, etc. What’s more, you can also test calls directly from that page. You don’t have to dig into source code to understand APIs. And using or changing your service is much easier, don’t you think? Let’s say some words about how to implement them in our project lifecycles. There are two main approaches to defining swagger: as a contract before development or autogenerating that based on created service code. Both of them have their own cons and pros. Defining swagger file as an API contract before touching a code allows us to parallel work between different teams dependent on that service and create typescript types based on that (useful when your backend is written in Node and you want to share types between repositories). But also requires more effort— all endpoints have to be defined manually and some later changes in service may be missed (developers have to remember about changes in two places). On the other hand, you can use annotations to generating swagger files automatically, based on source code — using libraries available for almost all languages. Thanks to that you don’t have to worry about updating documentation, but all consumers have to wait for a working version of API to start their work and some comments. Nevertheless, no matter which option is better in your case, using swagger definitely can take your API documentation to a completely new level.
Please, don’t waste your and others' time on manually checking indents or formatting rules. And write them down instead of saying “We always do it that way” during code review. I know that “spaces vs tabs” is a holy war in programming but you have to decide that battle for your team. Add tools like eslint or prettier and a set of rules to your repository. Automate that checks. Test your formatting on pre-commit or creating merge requests. Define rules in a transparent way — not only in your head. And let a computer do that simple checks — it is the best at that!
Please, don’t waste your and others' time on manually checking indents or formatting rules. And write them down instead of saying “We always do it that way” during code review. I know that “spaces vs tabs” is a holy war in programming but you have to decide that battle for your team. Add tools like eslint or prettier and a set of rules to your repository. Automate that checks. Test your formatting on pre-commit or creating merge requests. Define rules in a transparent way — not only in your head. And let a computer do that simple checks — it is the best at that!