❤ Micro service development Swagger (recommended Collection)

Keywords: Java Spring Boot RESTful


1. The role and concept of Swagger

Official address: https://swagger.io/

Swagger is a standardized and complete framework for generating, describing, invoking and visualizing RESTful Web services and integrating swagger to automatically generate API documents.

Swagger's goal is to define a standard and language independent interface for REST API, so that people and computers can discover and understand services without accessing source code, documents or network traffic monitoring. When properly defined by swagger, users can understand the remote service and interact with the remote service with minimal implementation logic. Similar to the interface implemented for the underlying programming, swagger eliminates the guesswork that may occur when invoking services.

1. Swagger's advantages

  • Support API to automatically generate synchronized online documents: after using Swagger, you can directly generate documents through code, and you no longer need to write interface documents manually. It is very convenient for programmers and can save time to write documents to learn new technologies.
  • Provide Web page online testing API: documents alone are not enough, and the documents generated by Swagger also support online testing. After the parameters and format are set, directly enter the value corresponding to the parameters on the interface to test the interface online.

2. SwaggerUI features

  1. The dependency free UI can be used in any development environment, either locally or on the Web side.
  2. Humanization allows end developers to interact easily and try every operation exposed by the API for ease of use.
  3. Easy to navigate, organized documents quickly find and use resources and endpoints.
  4. All browsers support Swagger UI, which can be used in all major browsers to accommodate all possible situations.
  5. Fully customizable. Set up and adjust the Swagger UI in the way you want through complete source code access.
  6. Full OAS supports visualization of API s defined in Swagger 2.0 or OAS 3.0

Front and rear end separation:

Current mainstream front and rear end development: Vue + SpringBoot

Back end era: the front end only manages static pages; html = = back end. Template engine JSP = > the back end is the main force

Era of front and rear end separation:

  • Back end: back end control layer, service layer, data access layer [back end team]

  • Front end: front end control layer, view layer [ front end team ]

    • Forge back-end data, json. Before the back-end development, there is no need for the back-end, and the front-end engineer can still run the project.
  • How does the front and back end interact? = > API

  • The front and rear ends are relatively independent and loosely coupled;

  • The front and back end can even be deployed on different servers.

Create a problem

The front-end and back-end integration and joint commissioning, and the front-end personnel and back-end personnel failed to "negotiate in time and solve it as soon as possible", resulting in the centralized outbreak of problems;

Integration of Swagger in SpringBoot


  • First, specify the scheme to update the latest API in real time to reduce the risk of integration.

  • In earlier years, Word planning documents were developed

  • Front and rear end separation:

    • Front end test and back-end interface use: Postman tool.
    • The back end provides interfaces: the latest changes and messages need to be updated in real time.

Swagger solved this problem well

  • It is known as the most popular API framework in the world.
  • Restful API document online automatic generation tool, and API documents are updated synchronously with API definitions
  • Run directly, you can test the API interface online.
  • Support multiple languages, such as Java, Php and other high-level languages

2. SpringBoot integration Swagger

1. Create a new springboot web project

2. Guide Package

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->

3. Write HelloController and test to ensure successful operation!

public class HelloController {

   @RequestMapping(value = "/hello")
    public String Hello(){
        return "Hello Swgger!";


4. To use Swagger, you need to write a configuration class SwaggerConfig to configure Swagger

@Configuration //Configuration class
@EnableSwagger2// Turn on automatic configuration of Swagger2
public class SwaggerConfig {  


5. Access test: http://localhost:8080/swagger-ui.html, see the interface of swagger;

3. Configure Swagger

1. The Swagger instance Bean is a Docket, so configure Swagger by configuring the Docket instance

@EnableSwagger2 // Turn on automatic configuration of Swagger2
public class SwaggerConfig {
    //bean instance of dock configured with Swagger
    public Docket docket(Environment environment){
      return new Docket(DocumentationType.SWAGGER_2);

2. Configure document information through apiInfo() property (all)

package com.kk.swagger.config;

import com.kk.swagger.controller.HelloController;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@EnableSwagger2 // Turn on automatic configuration of Swagger2
public class SwaggerConfig {

    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("KK1");

    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("KK2");

    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("KK3");

    //bean instance of dock configured with Swagger
    //enable whether to start Swagger. If false, Swagger can no longer be accessed in the browser
    public Docket docket(Environment environment){

        //Set the environment in which Swagger is displayed
        Profiles profiles=Profiles.of("dev","test");
        //Get the environment of the project, and judge whether it is in its own set environment through environment.acceptsProfiles
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                //RequestHandlerSelectors configure how interfaces are to be scanned
                //basePackage specifies the package to scan
                //any() scan all
                //none() does not scan
                //The annotation parameter on the withClassAnnotation scanning method is a reflection object of an annotation
//                . apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) will only scan methods with RestController on the class
                //  What paths does. paths() filter
//                .paths(PathSelectors.ant("/kk/**"))
    private static final Contact DEFAULT_CONTACT =new Contact("KK","HTTP","666@qq.com");
    //Configure Swagger apiInfo
    private ApiInfo apiInfo(){
        return new ApiInfo("KK of SwaggerAPI file", "Api Documentation",
                "1.0", "urn:tos", DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());



# apply name
# Application service WEB access port






4. Entity configuration

1. Create a new entity class

package com.kk.swagger.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
//@Api (note)
@ApiModel("User entity class")
public class User {

    @ApiModelProperty("user name")
    public String username;
    public String password;

2. As long as the entity is on the return value of the request interface (even generic), it can be mapped to the entity item:

//As long as there is an entity class in the interface, the return value will be scanned into Swagger
@PostMapping(value = "/user")
public User user(){
    return new User();


You can configure some comments for the requested interface

//The Operation interface is not placed on the class, but on the method
@ApiOperation("Hello control class,Post test")
@PostMapping(value = "/postt")
public User postt(@ApiParam("user name") User user){
  return user;

5. Other skin

Guide Package

<!--        skin peeler-->
        <!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui -->

visit http://localhost:8080/doc.html

There are many more. You can check it online

nrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui -->


  **visit http://localhost:8080/doc.html**

==There are many more. You can check it online==

Posted by jeremyphphaven on Sat, 09 Oct 2021 18:38:57 -0700