A super simple way to use Swagger in SpringBoot

Time:2022-9-20

Swagger is known as the most popular Api framework in the world, and it is a RestFul-style Api. Documentation online automatic generation tool: Api documentation and API definitions are updated synchronously. Can run directly, can test API interface online; support multiple programming languages: (Java, PHP, etc.).

Official website:https://swagger.io/

It is too troublesome for springBoot to use swagger, and you need to write config every time? If I tell you there is such a way, you only need to configure the yml file, do you learn or not?

Integrate Swagger

rely:


<!-- Swagger -->
<dependency>
    <groupId>com.battcn</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>2.1.5-RELEASE</version>
</dependency>

Everyone should have discovered the Swagger here. It is not official. This is a third-party integration, and the configuration is simpler.

Detailed configuration

Detailed configuration:

spring:
  swagger:
    enabled: true
    title: title
    description: description information
    version: system version number
    contact:
      name: maintainer information
    base-package: the base package for swagger scanning, default: full scan (can not be configured here in case of grouping)
    #Global parameters, such as authentication information such as Token, can be configured globally
    global-operation-parameters:
    - description: 'Token information, required'
        modelRef: 'string'
        name: 'Authorization'
        parameter-type: 'header'
        required: true
    groups:
      basic-group:
        base-package: com.battcn.controller.basic
      system-group:
        base-package: com.battcn.controller.system

my configuration

spring:
  swagger:
    title: Starry Sky Cabin - Article Microservice Interface
    description: Article microservice related interfaces, including articles, modules, knowledge point management, etc.
    version: 1.0.0 - SNAPSHOT
    contact:
      name: cv big devil
      email: [email protected]
    host: localhost
    enabled: true
    security:
      filter-plugin: true # Configure account password
      username: root
      password: root

Configure the interceptor, followed by the interceptor configuration. If readers need to use it in their own projects, please modify the original interceptor configuration and ignore the following paths to avoid being blocked and inaccessible. &quot;swagger-ui.html&quot;, &quot;static/css/“, “static/js/”, “swagger-resources”, “/**/error”, “v2/api-docs”

test use

run the project, visitIP+Port number/swagger-ui.html, for example, visit in the browser: http://127.0.0.1:13001/swagger-ui.html

image-20210221184645521

The effect after login:

image-20210221184734860

Review – Common Notes

For those who are familiar with swagger, please ignore the &quot;commonly used comment paragraph&quot;

`@Api`: used on the Controller class to describe the role of the class
  1. `value`=&quot;Description&quot;
  2. `description`=&quot;describe the role of this class in detail&quot;

@ApiOperation: Used in the Controller request method to describe the function of the method.

@ApiModel: Used when the request parameter is an object to describe the role of the object class

// use @ApiModel on the object class
@ApiModel(value=&quot;CategoryREQ object&quot;, description=&quot;Category query condition&quot;)
public class CategoryREQ extends BaseRequest<Category> {
}

@ApiModelProperty: Used when the request parameter is the attribute of the object, to describe the function of the object attribute.

  • value: Description of the property
  • hidden: Whether it is a query condition attribute, false: (default value) is displayed in the api document as a query condition; true is hidden, not a condition attribute
// request method parameter is CategoryREQ object
public Result search(@RequestBody CategoryREQ req) {}

@ApiModel(value=&quot;CategoryREQ object&quot;, description=&quot;Category query condition&quot;)
public class CategoryREQ extends BaseRequest<Category> {
    
    @ApiModelProperty(value = &quot;Classification Name&quot;)
    private String name;

    @ApiModelProperty(value=&quot;status(1: normal, 0: disabled)&quot;)
    private Integer status;
}
  • @ApiResponses: used on the method of the request to represent a set of responses
  • @ApiResponse:used in@ApiResponses, generally used to express an error response message, annotated parameters:
  • code: number, such as 400message: information, such as &quot;parameter filling error&quot;response: the class that throws the exception

@ApiIgnore: Use this annotation to ignore this API

@ApiImplicitParams: Used in the request method to add descriptions to multiple request parameters

@ApiImplicitParam: Can be used alone or in @ApiImplicitParams to add a description to a request parameter of a method.

  1. name:parameter name
  2. value: describes the role of the parameter
  3. dataType: parameter type, parameter type, default String, other values ​​dataType=&quot;Integer&quot;
  4. defaultValue: parameter default value
  5. required: Whether the parameter must be passed (true/false)
  6. paramTpye: Specify where the parameters are placed (header/query/path/body/form)

header: The parameter is submitted in the request headers @RequestHeader
query: Complete automatic mapping assignment directly with parameters @RequestParam
path: Submit data in the form of path variables @PathVariable
body: Submitting as a stream only supports POST (not commonly used)
form: Submitting in the form of a form only supports POST (not commonly used)
reference:

// The request method has multiple request parameters size, current
@ApiImplicitParams({
    @ApiImplicitParam(name="current", value="页码", required=true, paramType="path",dataType="int"),
    @ApiImplicitParam(name=&quot;size&quot;, value=&quot;Number of records per page&quot;, required=true, paramType=&quot;path&quot;,dataType=&quot;int&quot;)
})
@ApiOperation(&quot;Query category list interface based on category name and status&quot;)
@PostMapping("/search/{current}/{size}")
Result search(@RequestBody CategoryREQ req, @PathVariable int current, @PathVariable int size);

So far, this article about the super simple method of using Swagger in SpringBoot is introduced here. For more information about using Swagger in SpringBoot, please search for the previous articles of developpaer or continue to browse the related articles below. I hope you will support developpaer more in the future!