Forem: Paladuta Stefan

Why encourage to use JSTL in your legacy projects over JSP scriptlet?

Paladuta Stefan — Sun, 06 Aug 2023 11:58:40 +0000

This article will be a short and will represent maybe just a memo on why you as Team Leader should impose (or encourage) to your team the use of JSTL or/and even migrate piece by piece your current JSP’s written with scriptlet into JSTL syntax.

The arguments:

The human nature

If we write or maintain the .jsp pages in scriptlet code, believe me when I say that because of stressful situations (deadlines on projects or on features) or maybe because of commodity lot of things will be done in dumb ways. When I say dumb ways I mean that you will end up after a lot of time with a tone of things in FrontEnd written in .jsp as scriptlet that for sure should have been done in BackEnd. An example that I always saw in my time is that a lot of collections are sent in FrontEnd and the developer constructs a complete new collection from 0 and even does some calculations on it (that aren’t advanced but for sure they have no place in FrontEnd in this architecture).

Using jstl syntax is very limited (that’s the beauty) will impose to the developers to stop putting everything in FE and start thinking what should the BE provide already. Meanwhile the FE with the jstl will do small things in his limitation like iteration, conditional check, formatting some data, etc. nothing crazy that the classic scriptlet would have done.

Visually pleasant

I don’t know about you but I never saw in my company on the legacy application (that is over 15 years) code written in .jsp that doesn’t do crazy stuff ([…] the worst I seen his connection to DB, recovery of data , transforming that data, displaying that data […]) and looks ugly. Instead after 1 years of putting my team to try to use jstl when possible some pages for us developers are now more clearer (even found old bugs).

BAD:

<html>
  <head>
    <title>Count to 10 in JSP scriptlet</title>
  </head>
  <body>
    <%
    for(int i=1;i<=10;i++)
    {%>
     <%=i%><br/>
     <%
     }
     %>
  </body>
</html>

NICE:

<%@ taglib uri="http://java.sun.com/jstl/core" prefix="c" %>
<html>
 <head>
  <title>Count to 10 Example (using JSTL)</title>
 </head>

 <body>
  <c:forEach var="i" begin="1" end="10" step="1">
   <c:out value="${i}" />
   <br />
  </c:forEach>
 </body>
</html>

What is the cost ?

For you as developers ? nothing because we should know to do this, writing clean code instead of bad code shouldn’t even be an argument.

For the client ? if we don’t have experience in JSTL well some patience.

REMEMBER: Let the service layer have the business logic and determine what data the JSP needs.

If you liked the article please take a minute to offer me a clap 👏 or even buy me a coffee https://www.buymeacoffee.com/stefansplace (;

Based on the number of claps I will know if writing some tricks about this old concept is still wanted.

My main article: https://medium.com/@stefan.paladuta17/why-to-encourage-to-use-jstl-in-your-legacy-projects-over-jsp-scriptlet-4dd36e95ce00

Bash | Why should you put shell variables always between quotation marks ? (+ real world example)

Paladuta Stefan — Wed, 26 Jul 2023 10:32:09 +0000

This memo will help you understand how using quotation marks around shell variables can help ensure that they are interpreted correctly and can help avoid unexpected behavior.

You should put shell variables inside quotation marks to ensure that they are interpreted correctly by the shell. When you use a variable in a shell command or script without quotation marks, the shell will expand the variable, which means it will replace the variable with its value. This can cause problems if the variable contains spaces, special characters, or other characters that the shell interprets in a special way.

By enclosing the variable in quotation marks, you tell the shell to treat the entire string as a single argument, even if it contains spaces or other special characters. This can prevent errors and unexpected behavior in your shell commands and scripts.

For example, consider the following code:

MYVAR="Hello World"
echo $MYVAR

Without quotation marks, Bash will split the value of MYVAR into two separate words, "Hello" and "World", and treat them as separate arguments to echo, resulting in the output:

Hello World

However, if you put the variable in double quotes, like this:

MYVAR="Hello World"
echo "$MYVAR"

The entire value of MYVAR is treated as a single argument to echo, resulting in the output:

Hello World

Similarly, if your variable contains special characters such as asterisks or question marks, Bash will interpret them as globbing patterns and try to expand them into filenames in the current directory. This can lead to unexpected behavior or errors. Using quotes can prevent this behavior and ensure that the variable is treated as a literal string.

Therefore, it is generally a good practice to always put your shell variables inside double quotes unless you have a specific reason not to.

Real world example of bad management of quotation in shell scripting.

Consider the following scenario:

EX_VARIABLE="24/22/2021"
SQL_MSG=`sqlplus -s <user>/<pwd>@<db> <<-EOF
   whenever SQLERROR EXIT SQL.SQLCODE ROLLBACK;
   whenever OSERROR  EXIT SQL.SQLCODE ROLLBACK;

   select to_date('${EX_VARIABLE}','dd/mm/yyyy') from dual;

EOF`
if [ $? -eq 0 ]; then
   echo "OK";
else
   echo ${SQL_MSG}
fi

The objective of this shell script is to check if the conversion from the string representation of a date (stored in the EX_VARIABLE variable) is working properly by evaluating whether it is a valid date.

# ./sh_example.sh

select to_date('24/22/2021','dd/mm/yyyy') from dual bin boot dev 
docker-entrypoint-initdb.d etc home lib lib64 media mnt 
opt proc root run sbin sh_example sh_example.sh srv sys tmp u01 
usr var ERROR at line 1: ORA-01843: not a valid month

However, due to the lack of quotation marks around the SQL_MSG variable in the echo statement, the output includes extraneous information, such as the names of all the files in the current directory and if we check the content of the path where the shell is present:

we can see that the junk in fact represents all the files and logs from that specific folder !

bin
boot
dev
docker-entrypoint-initdb.d
etc
var
etc.

Reason of the behaviour

If we revisit the shell code again:

EX_VARIABLE="24/22/2021"
SQL_MSG=`sqlplus -s <user>/<pwd>@<db> <<-EOF
   whenever SQLERROR EXIT SQL.SQLCODE ROLLBACK;
   whenever OSERROR  EXIT SQL.SQLCODE ROLLBACK;

   select to_date('${EX_VARIABLE}','dd/mm/yyyy') from dual;

EOF`
if [ $? -eq 0 ]; then
   echo "OK";
else
   echo "${SQL_MSG}" #This was the only line of code changed
fi

but this time we are going to rewrite the line “echo ${SQL_MSG}”, more specific the variabile ${SQL_MSG} with quotation marks and run the shell again:

root@9ea9fad92c38:/# ./sh_example.sh
select to_date('24/22/2021','dd/mm/yyyy') from dual
               *
ERROR at line 1:
ORA-01843: not a valid month

we can see that this time it worked but what happened ?

Because the quotation marks were missing my theory is that the echo command tried to do echo of each of the lines that we see in the output:

echo select to_date(‘24/22/2021’,’dd/mm/yyyy’) from dual
echo * <- and echo * actually is a command that returns you the list of all the files and folder from the current directoy so the junk that we saw in red is actually the result of this command
echo ERROR at line 1:

If you liked the article please take a minute to offer me a clap 👏 or even buy me a coffee https://www.buymeacoffee.com/stefansplace (;

Original post: https://medium.com/@stefan.paladuta17/bash-why-should-you-put-shell-variables-always-between-quotation-marks-real-world-example-ac794dd53a84

SWAGGER | Bye Bye swagger specifications and welcome OpenAPI specifications (springfox implementation v3 gone wrong)

Paladuta Stefan — Sat, 15 Jul 2023 10:54:15 +0000

The main article that bundles all together and redirects to different features that you can implement in swagger UI is present here: https://medium.com/@stefan.paladuta17/spring-boot-using-swagger-at-maximum-9828ae9fb9d0

In this article I am going to present what the implementation of springfox v3 (that is complain with OpenAPI specifications) brings to the table.

The article will be divided in the following chapters:

Chapter 1 Introduce the feature in your project.
Chapter 2 Is there a need for annotation to enable OAS 3.0 ?
Chapter 3 Disable for production environment swagger.
Chapter 4 Problems with the 3rd version

Before starting here are some link(s) that you may be interested in:

Repository of springfox: https://github.com/springfox/springfox
Release notes for the version3: https://newreleases.io/project/github/springfox/springfox/release/3.0.0

Chapter 1 Introduce the feature in your project

Step 1 Introduce the dependency in your spring boot project (in pom.xml):

<dependency>  
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

Step 2 Creating a Controller , a Dto and a config class to store the Docket Bean

the controller:

import java.util.ArrayList;
import java.util.List;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import ro.stefan.dto.Book;

@RestController
@Api(tags = "Book Controller")
public class BookController {

    @GetMapping("/books")
    public List<Book> getBooks(){
        return new ArrayList<Book>();
    }

    @GetMapping("/ping")
    public String ping() {
        return "pong";
    }
}

the dto:

public class Book {
    private String title;

    private String author;

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public String getAuthor() {
        return author;
    }

    public void setAuthor(String author) {
        this.author = author;
    }

}

the configuration docket:

import java.util.HashSet;
import java.util.Set;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.RestController;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SpringFoxConfig {

    @Bean
    public Docket getDocketInstanceEx1() {
        final Set<String> produces = new HashSet<String>();
        produces.add(MediaType.APPLICATION_JSON_VALUE);
        produces.add(MediaType.APPLICATION_XML_VALUE);

        return new Docket(DocumentationType.OAS_30)
                .apiInfo(new ApiInfoBuilder()
                        .title("Note API")
                        .description("A CRUD API to demonstrate Springfox 3 integration")
                        .version("0.0.1")
                        .license("MIT")
                        .licenseUrl("https://opensource.org/licenses/MIT")
                        .build())
                .produces(produces).consumes(produces)
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .build();
    }

}

Step 3 Access to the generated OpenAPI

Location: http://localhost:/v3/api-docs and the result is:

This version of springfox implementation fills a lot of gaps that another project called springdoc-openapi had addressed for a long time.

Before going further I will remind everybody that:

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API.
Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs.

Chapter 2 Is there a need for annotation to enable OAS 3.0 ?

This question is actually thanks to https://www.springcloud.io/post/2022-02/springboot-swagger3/#gsc.tab=0 that explains the fact why some tutorials guide you to add the annotation @EnableOpenApi to enable OpenAPI. Actually is wrong (or useless) and actually if you already have a workable project with this annotation, just remove it and tell me the contrary. But why ? because if you go into the jar springfox-boot-starter-3.0.0.jar you can find a spring.factories. Opening the file (.jar):

the following content is presented:

# Auto Configure
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
springfox.boot.starter.autoconfigure.OpenApiAutoConfiguration

NOTE: For people not familiar with Spring Boot this is a Spring Boot-specific SPI file that automatically discovers and registers the configuration of the Starter component.

And if you use your eclipse (with JadClipse — decompiler) to look inside the jar:

we can find in the class: OpenApiAutoConfiguration with the piece of code:

@ConditionalOnProperty(value = “springfox.documentation.enabled”, havingValue = “true”, matchIfMissing = true)

that makes the annotation @EnableOpenApi uselless, because the interface that represents the annotation is importing this class OpenApiDocumentationConfiguration.class

@Import(OpenApiDocumentationConfiguration.class)
public @interface EnableOpenApi {
}

that already activates swagger by default.

Chapter 3 Disable for production environment swagger

NOTE: This is not a feature really of v3, but actually a trick using the previous chapter.

Imagine that if you are like me a developer working in a company your software will go through multiple environments: DEVELOPING, TESTING, UAT (User Acceptance Tests), PRODUCTION (just as example) and we for sure don’t want in PRODUCTION to permit the Spring Boot project to generate a Swagger-UI (not always but in my case yes).

For sure this is possible and quite simple if you read my previous Chapter 2 you have seen that we found a class called: OpenApiDocumentationConfiguration.class that we know is responsible to enable or disabled swagger-ui (by default it’s ON), to turn it OFF we simply must go to our application properties or yaml (depends what we choose to have in our spring boot app) and write the following config if you are using .yaml format:

springfox:
  documentation:
    enabled: false

or this format if you are using .properties format

springfox.documentation.enabled=false

and that’s all, now the url to swagger-ui will not work anymore.

Chapter 4 Problems with the 3rd version

Even if I’m very dear to swagger I think it was some very big problems regarding code pollution that I hope I have time to write an article about. I wanted to show you guys a lot of new feature that SpringFox implementation brings with the OpenAPI specifications but sadly most of them are buggy or are done wrong, an example is the concept of multiple servers:

As many things this feature is buggy and not working properly: https://github.com/springfox/springfox/issues/3483 and we waited for too long for such a simple feature to be working again. With other words in the next weeks I will be more focus on displaying some alternatives to SpringFox. If I will discover new stuff I will keep this page updated.

Second problem is the lack of transparency. A lot of milestone was set on this project but none of them presented for you as consumer a release date thus making you feel unsecure regarding what to do, to wait or not ? Sadly it’s clear that we as developers can’t wait and we must go forward with projects that are more active like spring-doc (that I will cover in future articles).

Third problem that scared me is the number of things I did on old microservices projects (SpringBoot 2.6.0) because OAS 3.0 from springfox didn’t work, more details can be found here: https://stackoverflow.com/questions/70178343/springfox-3-0-0-is-not-working-with-spring-boot-2-6-0

NOTE: This is my personal opinion and should be taken as being just a view on the project springfox. Again this project is dear to me and I really wanted to talk about it a lot but I want to deliver more value, not to wait for miracles.

If you liked the article please take a minute to offer me a clap 👏 or even buy me a coffee https://www.buymeacoffee.com/stefansplace (;

Original post: https://medium.com/@stefan.paladuta17/swagger-spring-boot-bye-bye-swagger-specifications-and-welcome-openapi-specifications-7eab7e68d6d7

Spring Boot | Using SWAGGER at maximum — All annotations that we should know about in springfox implementation

Paladuta Stefan — Sat, 15 Jul 2023 08:19:15 +0000

The main article that bundles all together and redirect to different features that you can implement in swagger UI is present here: https://medium.com/@stefan.paladuta17/spring-boot-using-swagger-at-maximum-9828ae9fb9d0

In this article I am going to show the most important annotations I used from the springfox implementation starting on the swagger version2 specifications.

The article will be divided in the following chapters:

Chapter: @Api annotation
Chapter: @ApiOperation annotation
Chapter: @ApiModel annotation
Chapter: @ApiModelProperty annotation
Chapter: @ApiIgnore
Conclusion

Chapter: @Api annotation

If you ever find a tutorial that tells you apply the following snippet of code and everything will work smooth as butter:

...
@RestController
@Api( description = "Book controller description | Api Annotation")
public class BookController {

   @GetMapping("/books")
   public List<Book> getBooks(){
     return new ArrayList<Book>();
   }
}

well wrong. If you follow me and my articles you know that I am a big advocate of creating tutorial materials AND maintaining them up to date as much as possible, as we don’t need more junk on internet but we actually need to filter them and make them better.

So going back to the problem. The lovely description attribute of the annotation @Api used for adding a description has been deprecated. By default, swagger api generates an empty description for the REST API class name.

Now in present this attribute “description”:

So what is the solution ? Simple, the attribute tags. Example of using the tags attribute:

....
@RestController
@Api( tags = "Book controller description | Api Annotation")
public class BookController {

   @GetMapping("/books")
   public List<Book> getBooks(){
     return new ArrayList<Book>();
   }
}

and the result:

Are there limits and/or tips&tricks you can use ? Well, based on my tests:

Tip&Trick: We can add emojis (:

.....
@RestController
@Api( tags = "Secret 📚 endpoints")
public class BookController {
   @GetMapping("/books")
   public List<Book> getBooks(){
      return new ArrayList<Book>();
   }
}

Limit: We can’t abuse the number of characters that we write in the tags value, so take care please.

Tip&Trick: The attribute can actually accept an array of tags (strings) and put the same endpoint in multiple points

Example of the code:

package ro.stefan.controller;
import java.util.ArrayList;
import java.util.List;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import ro.stefan.dto.Book;
@RestController
@Api( tags = {"books","store","something else"})
public class BookController {

 @GetMapping("/books")
public List<Book> getBooks(){
  return new ArrayList<Book>();
 }
}

Chapter: @ApiOperation annotation

You could further customize the description at an operation level by using @ApiOperation annotation.


@RestController
@Api( tags = "Book Store | API annotation")
public class BookController {

 @ApiOperation(value = "Recover the collection of all books from the store | API Operation annotation")
 @GetMapping("/books")
 public List<Book> getBooks(){
  return new ArrayList<Book>();
 }
}

Chapter: @ApiModel

@ApiModel is an annotation used to enhance the resource model description. We can use @ApiModel for the entire model class.

snippet of some code:

import io.swagger.annotations.ApiModel;

@ApiModel(description = "Model retrieved from library system")
public class Book {
  private String title;
  private String author;

  public String getTitle() {
    return title;
  }
  public void setTitle(String title) {
    this.title = title;
  }

  public String getAuthor() {
    return author;
   }
  public void setAuthor(String author) {
    this.author = author;
  }
}

Before:

After:

Chapter: @ApiModelProperty

@ApiModelProperty like @ApiModel is used enhance the resource model description but in this case for the individual attributes of the model class.

Snippet of some code (also with the @ApiModel annotation from previous chapter):

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "Model retrieved from library system")
public class Book {

  @ApiModelProperty(notes = "Title of the book", example = "Inside of this hell")
  private String title;

  @ApiModelProperty(notes = "Author of the book", example = "Stefan P.")
  private String author;

  public String getTitle() {
    return title;
  }
  public void setTitle(String title) {
    this.title = title;
  }
  public String getAuthor() {
    return author;
  }
  public void setAuthor(String author) {
    this.author = author;
  }
}

Before:

After (also with the @ApiModel annotation from previous chapter):

Chapter: @ApiIgnore

Let’s say that you have a project and like every new project when you build it you construct an endpoint that must act as test, to see if the base code is working if the C.I./C.D. is fine etc. Over the years I found a lot of endpoints made with this reason that remained until deploy in production. Honestly (in present with my current experience) I think they are very good to have.
An example of what I currently use is an endpoint called /ping that displays the up time of the microservices, the libraries used inside and their versions.

For this example I use the following controller:

import java.util.ArrayList;
import java.util.List;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import ro.stefan.dto.Book;
import springfox.documentation.annotations.ApiIgnore;

@RestController
@Api( tags = "Book Store | API annotation")
public class BookController {

  @ApiOperation(value = "Recover the collection of all books from the store | API Operation annotation.")
  @GetMapping("/books")
  public List<Book> getBooks(){
    return new ArrayList<Book>();
  }

  @ApiIgnore 
  @GetMapping("/ping")
  public String ping() {
    return "pong";
  }
}

with a simple method /ping that just returns a pong string. So after applying (uncomment) the code we can see that the interface swagger-ui displays nothing regarding /ping

but if we call the endpoint:

it exists so this is a success we as developers know a secret endpoint ;). And nobody that is consuming our contract (reading the swagger-ui) will know (normally speaking).

Conclusion: There are many other annotations offered by Spring but in reality this are the ones that I want to focus on because they are the most common ones you will ever see in projects if not more than you will ever see for version 2 of the swagger specifications. The next step is not to learn more annotations on this example/series but to move to the next version (v3 focused on OpenAPI object).

If you want my code you can find it here: https://github.com/Kanames/SpringBoot-SwaggerExamples

If you liked the article please take a minute to offer me a clap 👏 or even buy me a coffee https://www.buymeacoffee.com/stefansplace (;

My original article: https://medium.com/@stefan.paladuta17/spring-boot-using-swagger-at-maximum-all-annotations-that-we-should-know-about-in-springfox-e419e575b078

Spring Boot | Using SWAGGER at maximum — Docket advanced details

Paladuta Stefan — Sat, 08 Jul 2023 19:21:46 +0000

The main article that bundles all together and redirect to different features that you can implement in swagger UI is present here: https://medium.com/@stefan.paladuta17/spring-boot-using-swagger-at-maximum-9828ae9fb9d0

In this article I am going to show how to populate in more detail the Docket object used to generate the SWAGGER-UI that we all appreciate and use.

Chapter: Producing and Consuming
Chapter: Adding extra models
Chapter: Global request parameters default
Chapter: Global response default

Chapter 1 Producing and Consuming

Producing and consuming actions are two details that I personally appreciate when I see them in projects. It’s very nice and helpful when you see a documentation regarding an API that tells you as consumer what form of response it can give you: json, xml, custom response, etc. and what form of information you need to send, thus making the experience more valuable.

To set what is the API producing and consuming we can see the methods .produces() and .consumes() on the Docket object. These two methods expect from you, a collection of type Set of what forms will the application accept/offer. In case you are wondering why Set collection, you just need to simply remember: “A Set is a Collection that cannot contain duplicate elements.” which with other words means the UI should render only unique forms thus a Set is perfect for this case.

A basic example of the entire class with the Docket object populated for consuming:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.MediaType;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class SpringFoxConfig {

 @Bean
 public Docket getDocketInstance() {
  final Set<String> produces = new HashSet<String>();
  produces.add(MediaType.APPLICATION_JSON_VALUE);
  produces.add(MediaType.APPLICATION_XML_VALUE);
  produces.add("Stefan's custom mapping value");

  return new Docket(DocumentationType.SWAGGER_2)
    .produces(produces)
    .select()
    .apis(RequestHandlerSelectors.basePackage("ro.stefan.controller"))
    .paths(PathSelectors.any())
    .build();
 }
}

NOTE: produces.add(“Stefan’s custom mapping value”); it’s here just to prove the concept that it’s just a string applied on that collection + you shouldn’t normally go outside of the standard defined MIME formats.

Before applying the changes:

After applying the changes:

Why do this ?

Because as mentioned already an API can accept and return data in different formats (json, xml, etc.) so we can useconsumes and produces to specify the MIME types understood by your API. To set the consumes and produces type is easy and just represents an array of MIME type.
This modification as presented in the examples are done globally so that means that all controllers from that spring boot project will render this but you can override this value at API level (method from the controller) if you have exceptions.

Important note: “Note that consumes only affects operations with a request body, such as POST, PUT and PATCH.” — swagger.io

What MIME type we can use ?

application/json
application/xml
application/x-www-form-urlencoded
multipart/form-data
text/plain; charset=utf-8
text/html
application/pdf
image/png etc...

Chapter 2 — Adding extra models

“A key feature offered by Springfox that was very appealing for reverse-engineering/retrofitting an existing Spring Boot microservice to generate an OAS was the ability to ad-hoc pick up POJOs and have a schema generated for it.” — https://github.com/springdoc/springdoc-openapi/issues/415.

I put the following quote because it expresses very simple the current chapter. Adding extra models in the SWAGGER-UI is actually a thing that I saw being used very often by other teams.

@Autowired
private TypeResolver typeResolver;

@Bean
public Docket getDocketInstanceEx1() {
    final Set<String> produces = new HashSet<String>();
    produces.add(MediaType.APPLICATION_JSON_VALUE);
    produces.add(MediaType.APPLICATION_XML_VALUE);

    return new Docket(DocumentationType.SWAGGER_2)
            .produces(produces)
            .consumes(produces)
            .additionalModels(typeResolver.resolve(Author.class))
            .select()
            .apis(RequestHandlerSelectors.basePackage("ro.stefan.controller"))
            .paths(PathSelectors.any())
            .build();
}

NOTE: Personally I never had a reason to do this but only because I didn’t have a reason or opportunity it doesn’t mean it’s useless I just never had the chance.

Why would you this ?

Based on my reason I just found the following:

This issue: https://github.com/springdoc/springdoc-openapi/issues/415 that explain that the desire to add extra models is to generate a bigger open API json. I wanted to simply generate the Open API spec yaml/json as a baseline with the existing Spring Boot controllers, but then manually write up summaries, descriptions, response types, and return types in the yaml itself. My primary use case here is for large existing microservices that weren’t built-out with an Open API or API driven development mindset. (Also, the return types of our controllers are almost always Strings because we serialize manually with GSON as opposed to Jackson w/ Spring, but I think swagger-core provides annotations that resolve this anyway)
Other teams/projects do this because they have old systems where the controller returns a generic String that represents an object in json format.

Chapter 3 — Global request parameters default

The method: .globalRequestParameters() is one of the most useful features we have in Docket. It allows you to add for all requests (all endpoints of the spring boot project) written in all controllers a parameter that can be:

Query parameter
Header attribute
Cookie
Path
Form
Body
Form Data

Values extracted from the springfox.documentation.service.ParameterType enum.

Example with header attribute:

package ro.stefan.config;

import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.MediaType;

import com.fasterxml.classmate.TypeResolver;

import ro.stefan.dto.Author;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.RequestParameterBuilder;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.ParameterType;
import springfox.documentation.service.RequestParameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SpringFoxConfig {  
  @Autowired
    private TypeResolver typeResolver;

    @Bean
    public Docket getDocketInstanceEx1() {
        final Set<String> produces = new HashSet<String>();
        produces.add(MediaType.APPLICATION_JSON_VALUE);
        produces.add(MediaType.APPLICATION_XML_VALUE);

        List<RequestParameter> listRequestParamters = new ArrayList<RequestParameter>();
        RequestParameter requestParamterToken = new RequestParameterBuilder()
                .name("ACCESS_TOKEN")
                .required(true)
                .query(q -> q.model(modelSpecificationBuilder -> modelSpecificationBuilder.scalarModel(ScalarType.STRING)))
                .in(ParameterType.HEADER)
                .build();

        listRequestParamters.add(requestParamterToken );
        return new Docket(DocumentationType.SWAGGER_2)
                .produces(produces)
                .consumes(produces)
                .globalRequestParameters(listRequestParamters)
                .additionalModels(typeResolver.resolve(Author.class))
                .select()
                .apis(RequestHandlerSelectors.basePackage("ro.stefan.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

//----------------------------------------------------------------------------------------------------------------------


import java.util.ArrayList;
import java.util.List;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import ro.stefan.dto.Book;

@RestController
public class BookController {

    @GetMapping("/books")
    public List<Book> getBooks(){
        return new ArrayList<Book>();
    }
}

so we can see now in the SWAGGER-UI the header attribute ACCESS_TOKEN is mandatory for the endpoint to be called. Thus avoiding to write code in Controller that is just used on an interceptor or filter.

Example with query parameter:

import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.MediaType;

import com.fasterxml.classmate.TypeResolver;

import ro.stefan.dto.Author;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.RequestParameterBuilder;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.ParameterType;
import springfox.documentation.service.RequestParameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SpringFoxConfig {

    @Autowired
    private TypeResolver typeResolver;

    @Bean
    public Docket getDocketInstanceEx1() {
        final Set<String> produces = new HashSet<String>();
        produces.add(MediaType.APPLICATION_JSON_VALUE);
        produces.add(MediaType.APPLICATION_XML_VALUE);

        List<RequestParameter> listRequestParamters = new ArrayList<RequestParameter>();
        RequestParameter limitParameter = new RequestParameterBuilder()
                .name("limit")
                .required(false)
                .query(q -> q.model(modelSpecificationBuilder -> modelSpecificationBuilder.scalarModel(ScalarType.STRING)))
                .in(ParameterType.QUERY)
                .build();
        RequestParameter pagesParameter = new RequestParameterBuilder()
                .name("pages")
                .required(false)
                .query(q -> q.model(modelSpecificationBuilder -> modelSpecificationBuilder.scalarModel(ScalarType.STRING)))
                .in(ParameterType.QUERY)
                .build();
        listRequestParamters.add(limitParameter);
        listRequestParamters.add(pagesParameter);

        return new Docket(DocumentationType.SWAGGER_2)
                .produces(produces)
                .consumes(produces)
                .globalRequestParameters(listRequestParamters)
                .additionalModels(typeResolver.resolve(Author.class))
                .select()
                .apis(RequestHandlerSelectors.basePackage("ro.stefan.controller"))
                .paths(PathSelectors.any())
                .build();
    }   
}

So… we can see that the line of code that dictates the types is .in(ParameterType.QUERY)

Example with cookie parameter:

If you want to see the entire code and example just visit my repository on GitHub and written at the bottom of this article.

Now as you can imagine the possibilities are big.

Why would you need this ?

Project’s where you have interceptors or filters and per each request sent by the client and you want to extract an information like a access token (jwt, etc.). It’s clear that you don’t write the token variable into the controller because the controller will never use the variable so instead of having a required variable written in Controller that will never be used there, you can avoid writing it and put it directly into the Docket property if the variable is mandatory for all request of your microservices.

Chapter 4 — Global response default

Swagger API’s allow you as developer to override the default response messages of different HTTP requests by telling it (swagger) the to stop using default responses .useDefaultResponseMessages(false) and starting to construct your own cases with the method: .globalResponses()

NOTE: Remember all of this methods are applied at Docket level.

So before overring it in swagger UI we will see that in case of 500 and 403 error messages we would get:

After applying the following code:

import java.util.ArrayList;
import java.util.List;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseBuilder;
import springfox.documentation.service.Response;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SpringFoxConfig {

    @Bean
    public Docket getDocketInstanceEx1() throws JsonProcessingException {
        List<Response> listResponses = new ArrayList<Response>();

        class ServerError{
            private String serverIp;
            private String serverName;
            private String errorMsg;
            private String errorStack;

            public String getServerIp() {
                return serverIp;
            }
            public void setServerIp(String serverIp) {
                this.serverIp = serverIp;
            }
            public String getServerName() {
                return serverName;
            }
            public void setServerName(String serverName) {
                this.serverName = serverName;
            }
            public String getErrorMsg() {
                return errorMsg;
            }
            public void setErrorMsg(String errorMsg) {
                this.errorMsg = errorMsg;
            }
            public String getErrorStack() {
                return errorStack;
            }
            public void setErrorStack(String errorStack) {
                this.errorStack = errorStack;
            }

        }

        ObjectMapper objMapper = new ObjectMapper();
        listResponses.add(new ResponseBuilder().code("500").description(objMapper.writeValueAsString(new ServerError())).build());
        listResponses.add(new ResponseBuilder().code("403").description("Forbidden!!!!!").build());


        return new Docket(DocumentationType.SWAGGER_2)      
                .useDefaultResponseMessages(false)
                .globalResponses(HttpMethod.GET,listResponses)
                .select()
                .apis(RequestHandlerSelectors.basePackage("ro.stefan.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

we can see:

So as you can imagine again this feature brings a ton of value to you as a user that offers API’s and value to a consumer that will bother you less because you documentation just got more precious.

Why would you need this ?

Because in an enterprise environment as much as I hate saying we must understand that we aren’t a team of 10 or 20 or 30 people we are a team over 300+ developers on different projects that are part of the same ecosystem so naturally if you let everyone define it’s own style the system wouldn’t be so optimal. So based on what I said this feature is used when the company architect say “All web services should have this standard response in case of failure (server) or non-auth.” thus reducing the complexity of the system and putting down a LAW (yes, I hate this but makes sense if you think about it at cold).

Conclusion: There are a lot of features that Docket object from swagger offers but please always take in consideration if the feature is old or deprecated and try to find something that is more up to date. Even this article presents things using the SWAGGER_2 version when now the hype is version 3.

If you want my code you can find it here: https://github.com/Kanames/SpringBoot-SwaggerExamples

If you liked the article please take a minute to offer me a clap 👏 or even buy me a coffee https://www.buymeacoffee.com/stefansplace (;

Original post: https://medium.com/@stefan.paladuta17/spring-boot-using-swagger-at-maximum-docket-advanced-details-6b72b334be21

Spring Boot | Using SWAGGER at maximum — ApiInfo

Paladuta Stefan — Mon, 03 Jul 2023 17:32:37 +0000

In this article I am going to show how to add ApiInfo object in your Docket so that you will have a more professional look on your Swagger UI.

ApiInfo is the object that allows you as a developer to add Contact information, descriptions of the API, terms of use, and other information that are less important from an implementation point of view but important from an organization point of view.

The majority of the time teams don’t focus at all on this small details because they bring no value to the API but as mentioned they bring value from the fact that it’s a small detail that can be part of a set of small details that together makes your application more enjoyable and most of all makes you proud of your work. We can consider it in IT “Nice to have…”

Adding ApiInfo couldn’t have been easier, so I present it by a simple example:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SpringFoxConfig {


    @Bean
    public Docket getDocketInstance() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfoExample01())
                .select()
                .apis(RequestHandlerSelectors.basePackage("ro.stefan.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfoExample01() {
        return new ApiInfoBuilder()
                .title("API Info - Title section")
                .description("API Info - Description section")
                .version("0.0.1")
                .contact(new Contact("Stefan", "https://medium.com/@stefan.paladuta17", "test@test.com"))
                .build();
    }

}

First we will see how the swagger-ui looks without ApiInfo:

Now we will see how the swagger-ui looks with ApiInfo:

So we can see that with the ApiInfo based on our example added a lot of new things:

Point 1: The title is now more personalized for your application, and this believe me it’s important when you manage a dozen of microservices each with their own swagger interface and you want to test them individually.

Point 2: We have a description section where we can add information that describes the point of this swagger interface or the business logic that this API’s expose.

Point 3: We expose an URL that can redirect the user to a main page of the developing team that manages this bundle of endpoints.

Point 4: We expose a way for someone to contact us. And this for me it’s the most important thing in an API world, you should make the effort to make the proper documentation for consumers and if that documentation is not enough then you should leave at least a way for them to contact you for a feedback.

Let’s get deeper in the details: the method .description() can be very powerful because we can add HTML code. Well actually it’s a bit fake the statement but in reality it’s called: CommonMark syntax (learn it and you can do amazing stuff).

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SpringFoxConfig {


  @Bean
  public Docket getDocketInstance() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfoExample02())
                .select()
                .apis(RequestHandlerSelectors.basePackage("ro.stefan.controller"))
                .paths(PathSelectors.any())
                .build();
  }

  private ApiInfo apiInfoExample02() {
        return new ApiInfoBuilder()
                .title("API Info - Title section")
                .description("API Info - <strong>Description</strong> section <br> testing something new <br> <table> <tr><td>1</td><td>2</td></tr> <tr><td>3</td><td>4</td></tr> </table>")
                .version("0.0.1")
                .contact(new Contact("Stefan", "https://medium.com/@stefan.paladuta17", "test@test.com"))
                .build();
    }

}

NOTE: the title and version properties are required, others are optional. The result:

Why should you dedicate precious minutes/hours on this small details ? if you don’t see the value, then just take as good practice as the smartbear company implies “[…] it is considered to be a good practice to include general information about your API into the specification: version number, license notes, contact data, links to documentation, and more.”

Conclusion: ApiInfo is an object that permits you as developer to populate your Swagger-UI with the following data:

The title
The description
The version ( + the url)
The Contact to join the API owner
The licence ( + the url)
The API vendor’s extension

thus making your API documentation look much professional and easy to read by any consumer and also enforce you or your team to keep an eye on small details (good practice).

If you want my code you can find it here: https://github.com/Kanames/SpringBoot-SwaggerExamples

If you liked the article please take a minute to offer me a clap 👏 or even buy me a coffee https://www.buymeacoffee.com/stefansplace (;

Spring Boot | Using SWAGGER at maximum — Grouping/Definition/Tag

Paladuta Stefan — Sat, 01 Jul 2023 13:33:05 +0000

In this article I am going to show how grouping/definitions/tags can be achieved in swagger UI.

Why should you bother to implement grouping in your application ?

Maybe you have an application that exposes a ton of endpoints and that means you may have developers that want to group them logically.
Maybe you have an application that has a ton of controllers that together, bundles the everything too tight (from an SWAGGER UI point of view) and separation should be applied.
Maybe you have an application that is presented as a monolith and exposes a ton of web services for different groups/teams. In this case you may want to divide them based for who they are exposed so that the UI generate via swagger won’t be huge and confusing but instead be directly focused on specific group of consumers.
Categorizing apis.

How to do grouping ?

1 — Using GROUPS

We create first the Docket’s. In my case I create 2 docket bean’s that will be for 2 groups (address and accounting):

package ro.stefan.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SpringFoxConfig {

    @Bean
    public Docket api1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("address")
                .select()
                .apis(RequestHandlerSelectors.basePackage("ro.stefan.external.apis.address"))
                .paths(PathSelectors.any())
                .build();
    }


    @Bean
    public Docket api2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("accounting")
                .select()
                .apis(RequestHandlerSelectors.basePackage("ro.stefan.external.apis.accounting"))
                .paths(PathSelectors.any())
                .build();
    }


}

the layout of the project is the following (also can be seen directly via my github repo. attached at the end of the article):

in this layout we have 2 basic controllers ( AccountingController and AddressController ) with just methods that return null that are put there just for the POC (Proof Of Concept). And the result:

we can see that the generate UI swagger has in the Select definition comboBox our 2 groups.

2 — Using TAGS

Using Tags it’s more interesting, here we don’t have anymore definitions (the combo box) but we define a proper grouping of endpoint. First I start with sharing the Docket code:

package ro.stefan.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Tag;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SpringFoxConfig {


    @Bean
    public Docket api3() {
        // here tags is optional, it just adds a description in the UI
        // by default description is class name, so if you use same tag using 
        // `@Api` on different classes it will pick one of the class name as 
        // description, so better define your own description for them
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .tags(new Tag("security", "security related"), 
                          new Tag("loan", "loan related"))
                .select()
                .apis(RequestHandlerSelectors.basePackage("ro.stefan.external.apis"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Openapi OAS3 with springfox ")
                .description("Code first approach")
                .version("1.0.0")
                .contact(new Contact("Stefan", "https://test.com", "test@test.com"))
                .build();
    }

}

the layout of the project is the following:

@RestController
public class AccountingController {

    @GetMapping("/accounts")
    public List<String> getAccounts(){
        return null;
    }
}
/* ----------------------- */
@RestController
public class AddressController {

    @GetMapping("/addresses")
    public List<String> getAddresses(){
        return null;
    }
}
/* ----------------------- */
@RestController
@Api(tags = "loan")
public class LoanController {

    @GetMapping("/loan")
    public String getLoanDetails() {
        return null;
    }
}
/* ----------------------- */
@RestController
@Api(tags = "security")
public class SecurityController {
    @GetMapping("/user")
    public String getUser() {
        return null;
    }
}

in this layout we have 4 basic controllers with just a method that return null but put there just for the POC (Proof Of Concept) and the result

Interesting, so by putting on 2 controllers the necessary annotation @Tag we just unlocked the power to change also the name of the group and the description.

We can see that 2 controllers that aren’t annotated with the @Tag are auto-generated their names (accounting-controller and address-controller) and the 2 controllers that we annotated with @Tag are named and descripted as we written in the Docket code.

You can have operations under multiple tags, but not tags under tags.

Conclusion: The concept of grouping API’s is not something specific to java here I encourage you to follow if you want to see the same principle applied for .NET Core, C#: http://www.mattruma.com/adventures-in-apis-grouping-controllers-in-swagger/

If you want my code you can find it here: https://github.com/Kanames/SpringBoot-SwaggerExamples

If you liked the article please take a minute to offer me a clap 👏 or even buy me a coffee https://www.buymeacoffee.com/stefansplace (;

References:
https://medium.com/p/2b25eb39a0cb

Microservices | Why should you think twice before migrating from a giant legacy application to microservices

Paladuta Stefan — Sat, 24 Jun 2023 13:49:52 +0000

There are millions of articles that say how great microservices are and how awesome it is to use them from several points of view, but this article is not meant to measure the greatest of the microservices infrastructure but tell you the real cost, that nobody is telling/displaying you about implementing this kind of infrastructure. To do this kind of migration from a legacy monolith to a microservices solution is not easy and actually I dare to use the words “horrible” and “stressful” when done complete wrong.

There aren’t many success strategies to implement it from a management point of view, but before starting please take in mind the following(s):

This is NOT a tutorial
This is NOT a measuring article or manifest regarding if microservices are bad or not.
This is NOT a story told from a Project Manager’s point of view. but it’s a story told from a developers point of view.

This article in exchange will attack the following points:

Are you a core system ?
Is your management aware of the costs ?
Is your team aware of the costs ?
Do you have someone in team that handled microservices in the past ?
Is your infrastructure stable ?

Background of my work

In my area of specialization my application is in reality an ecosystem of applications that lives inside a large monolith composed of multiple different type of applications that are also part of their own ecosystem.

You can think about this infrastructure like a StateMachine infrastructure where you have the core StateMachine that represents the starting point of everything, maybe like the login page (as an example) that redirects you to the internal system that has multiple search inputs , links, etc. And those links open themselves small/large application that are StateMachines.

To bring a little background my main focus is on Banking applications.

Point 1: Are you a core system ?

In every large company the system that in most cases is monolithic even today in 2022 (but can also be applied on the rest of types) you have at a high level, two types of modules/system/projects/components how ever you wish to call them

Type: core
Type: consumer

NOTE: “This is just my personal terminology, if I find a more used term I will update the article”

Core means that your application is focused not around interfaces (UI) for an end user but your business is focused on core concepts that must offer support to other systems to consume (consumers) your logic.

Example:

Core system: Payment System
Consumer: Loan System paying for installments If you are a core system in that case your life is much easier because the number of sub-calls you need to do to other sub-system is less to none, thus making your communication in infrastructure less messy.

But as a core system you have a lot of pressure to satisfy the following points:

Speed: your endpoints need to be as fast as possible you can’t have a reason to be slow, you as a core system that offers to other business need to think about how fast your endpoint is by using whatever strategy can be applied on your project (like caching or event based solutions). The reason if it’s not already clear is that, if consumers are coming to digest (call) your endpoint but that consumer represents a large business unit they can’t stay on your endpoint 1, 2 or 3 seconds, in my case if I see more than 800miliseconds we must have a discussions on what are you doing their.

Example:

In the above simple example we can see that an UI is responsible for creating online a loan for a client. It can have 2 sub call’s to systems that checks the credit line of an client and also creates an account for him if all is fine. But this simple communication with just 2 sub-system can take: 2s + 1.5s a total of 3.5 seconds and that’s without any business logic written on our UI part. So it’s clearly not fine and this should be the first call/sign to everybody, that you can’t migrate a product from a sync. communication environment to microservices and still want to have sync. communication and more speed, THAT’s impossible and breaks the basic rules of what microservices should be.

NOTE: Normally you shouldn’t have sync communication but normality is too costly and migrations should be as cheap as possible for the management so let’s move on.

Logic: your endpoints should be done in a logical manner like REST Infrastructure where it dictates in simple terms “SMART ENDPOINTS”.

Point 2: Is your management aware of the costs ?

If you think you know the cost of microservices then multiple it by 2 or 3. It may sound crazy but the cost of migrating an application that is already leaving and written in a monolith style is giant. Or even if you start creating new microservices with a new business but you lack the basic infrastructure to do so then I wish you good luck and may you finish the project with your mind still not lost.

First sub-point is management should understand the basics of microservices, not at technical level but at the level where a common ground can be found to explain the smallest and simplest elements of this infrastructure. Some elements that are a must for a management to know for this infrastructure, are:

API
REST
ENDPOINT
MONOLITH
SERVICES
CONTAINER
AUTHORIZATION
AUTHENTICATION
TRANSACTIONALITY

Second sub-point is management should know that to go to a microservice approach you should need a team structure that represent(s) correctly what you are trying to accomplish. For anyone that is new to infrastructure there is a law called “Conway’s Law” and states:

“Any organization that designs a system (defined broadly) will produce a design whose structure is a copy of the organization’s communication structure”

So that means that if your team is designed similar to this:

then that means that you are the type of organization that in general when you want to interact with DB people you raise tickets (Jira if you have Atlassian products) or mails to a group dedicated to DBA management thus making your software to look like in the above, a giant cake of layers.

In microservices this kind of structure is not going to get you far if you insist with this. But in ex-change it offers you the following clean solution:

Example in this image we see 3 team’s with a set of products or a product and this teams contains people focused on:

QA
UI
DBA
OPS
DEV
and more if the case needs to have..

This kind of organization actually boosts the people moral moreover, by giving the sense that they can climb some kind of hierarchy or job thus giving them something to be interested in giving a goal giving them something to focus them inside your company. At the end of the day isn’t it good for you as company to keep the people ?

Third sub-point is management should encourage the creation as many POC’s (Proof of concept) as possible so that nothing is lost in communication and everything that is proposed, is represented as small demo/POC to display what the goal must be in the end or at least a part of it.

Not doing POC’s will not give you a gasp on what really will result after the developing is finished, also a POC should show you if the system that we will have in the end is exactly like you thought about:

A POC or the DEMO should:

Show the FrontEnd that must be achieved
Should demonstrate via a large number if diagrams of all kind how the BackEnd is divided with reasoning + how the communication is done.
Present the con’s and pro’s
etc.

In short words Companies/Entities should invest money to get money, this in IT is called simply ARCHITECT DOCUMENT and will present everything that Management, QA team, Dev team, etc. will read understand and agree if it’s suitable for all.

Most people refuse to understand that if you start a project you must NOT fail it, but don’t gasp that as humans we make mistakes and making decisions without doing research will just make you lose money, time, and make your workers day a living hell. if after 3 month’s of generating the documents, schemes, diagrams , a POC you release that this can’t be maintain on this budget for this client, then it’s natural in my opinion to stop it and you learned something from this (YOU ALWAYS LEARN SOMETHING FROM FAILING).

Point 3: Is your team aware of the costs ?

sually (in my case) but also talking with other friends in other companies a migration is not done by the team that does the daily maintenance of the project but done by another team that was the role of coming doing the product in version 2.0 and then leave (what I like to call ninja’s).

At end when they leave the new product is given to the team that is doing the daily maintenance and continues to work on it like nothing happened.

Personal note: this kind of thing is brining value to the final actors and product, the actual team should be aware of what’s happening on the infrastructure and how to product will look because they know it better, to hire people with the purpose of rewriting but to know understand the business of the application is just stupid and the problem is on both side:

management: Not understanding that the start of this kind of project is not something that can be done overnight and key things should be first done, before accepting the migration and starting it:

Manual that describes the product
Sequence diagrams of simple teste cases and edge test cases.
Understanding the number of interactions of the current system with other systems
Understanding the business from a high level
Understanding the platform from were you are leaving and the consequences of not being their

external team: Not all persons that have this position of going from project to project have the passion to understand the business and generate a beautiful product with a wonderful codebase and excellent guidelines as much as we wish (not most, because in my cases I had an excellent collaboration with me external team) but in general people are focused on bringing as much business as possible and don’t care about the quality of the software as result.

Going back to the cost for the team that is doing the management, let’s see what the team should know:

What is the desired result of the migration ?
Does the new version of the product handles all scenarios ?
What is the new tech. stack that the team must know ?
What is the new infrastructure that the team must understand ?
What are the protocols for: production error, handling manual interventions, time to market.
How difficult is the debugging of the application ?
How difficult is to introduce new features ?

Point 4: Do you have someone in team that handled microservices in the past ?

In my opinion it’s critical for someone in the team to have handled in their past microservices infrastructure, especially when you aren’t starting a system from zero but your migrating from one big important monolith to microservices infrastructure.

Having someone in the team that handled in past this relative “new” infrastructure will save you :

Time in experiments
Bringing more cons or pros in decision making
Show what streets work on long/short run

Point 5: Is your infrastructure stable ?

If you are the kind of project that goes on an infrastructure that was already tested by another product then please ignore/skip this section.

But if you are the kind of project that is the first project that goes in this microservices world in your organization that means that you will also be the first one to test the infrastructure and before starting you should understand the following things as developer and then as a product manager:

You will be the tester of the infrastructure

As developer and product manager of course it’s going to be hard to understand this but this kind of infrastructure is very shaky when it’s so young in the company, things will shake and they shake hard until everybody learn’s to manage it.

In my personal view until the team responsible for servers were able to learn all, I had some rough times deploying, different stuff was failing ingress was failing, pods weren’t created, deployment weren’t updated and so on.

You must understand the infrastructure needs to be monitored

Tools that never existed in your organization may be without question inserted to help in debugging problems and monitoring distributed systems.

Thank you all for the time I can imagine this article may not be what you needed but I hope that it presented to you some points that you should take in consideration when trying to move from monolith’s to microservice’s just for the fun of having this buzzword in your company.

Please leave a comment and like if you appreciate it, if not please offer constructive criticisms in comments.

Originally posted on: https://medium.com/@stefan.paladuta17/microservices-why-should-you-think-twice-before-migrating-from-a-giant-legacy-application-to-d020075dd8b