How to use Swagger in SpringBoot

Integrating Swagger

Dependencies:

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

You may have noticed that the Swagger I have here is not official. This is integrated by a third party, and the configuration is simpler.

Configuration details

Detailed configuration:

spring:
  swagger:
    enabled: true
    title: 标题
    description: 描述信息
    version: 系统版本号
    contact:
      name: 维护者信息
    base-package: swagger扫描的基础包，默认：全扫描(分组情况下此处可不配置)
    #全局参数,比如Token之类的验证信息可以全局话配置
    global-operation-parameters:
    -   description: "Token信息,必填项"
        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: 星空小屋 - 文章微服务接口
    description: 文章微服务相关接口，包括文章、模块、知识点管理等
    version: 1.0.0 - SNAPSHOT
    contact:
      name: cv大魔王
      email: 1919301983@qq.com
    host: localhost
    enabled: true
    security:
      filter-plugin: true # 配置账号密码
      username: root
      password: root

Configure the interceptor, there is interceptor configuration later, if any readers need to configure it themselves For project use, please modify the original interceptor configuration and ignore the following paths to avoid being intercepted and resulting in inaccessibility. "swagger-ui.html", "static/css/", "static/js/", "swagger-resources", "/**/error", "v2/api-docs"

Test using

to run the project and access IP port number/swagger-ui.html, for example, access in the browser: http://127.0.0.1:13001/swagger -ui.html

The effect after logging in:

##Review - Commonly used annotations

For those who are familiar with swagger, please ignore the "common annotation paragraph"

`@Api`：用在 Controller 类上，描述该类的作用
  1. `value`="描述信息"
  2. `description`="详细描述该类的作用"

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

@ApiModel: Used when the request parameter is an object, describing the role of the object class

// 在对象类上使用@ApiModel
@ApiModel(value="CategoryREQ对象", description="类别查询条件")
public class CategoryREQ extends BaseRequest<Category> {
}

@ApiModelProperty: Used when the request parameter is On the properties of the object, describe the role of the object's properties.

• value: Description of the attribute

• ##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 conditional attribute

  // 请求方法参数是 CategoryREQ 对象
  public Result search(@RequestBody CategoryREQ req) {}
  
  @ApiModel(value="CategoryREQ对象", description="类别查询条件")
  public class CategoryREQ extends BaseRequest<Category> {
      
      @ApiModelProperty(value = "分类名称")
      private String name;
  
      @ApiModelProperty(value="状态(1:正常，0:禁用)")
      private Integer status;
  }

• @ApiResponses

  : Used in In the request method, it is used to represent a set of responses

##@ApiResponse
• : used in

  @ApiResponses, generally used to express an error Response information, annotation parameters:

code
• : number, such as 400

  message: message, such as "parameter filling error" response: The class that threw the exception

  ##@ApiIgnore
: Use this annotation to ignore this API

@ApiImplicitParams: Used on request methods to add descriptions to multiple request parameters

@ApiImplicitParam: Can be used alone or in @ApiImplicitParams to add descriptions to one request parameter of the method.

name

：Parameter name

1. value
：Describe the function of the parameter

2. dataType
: parameter type, parameter type, default String, other values ​​dataType="Integer"

3. ##defaultValue

   : Parameter default value

4. required

   : Whether the parameter must be passed (true/false)

5. paramTpye

   : Specify where the parameters are placed (header/query/path/body/form)

6. header

   : The parameters are submitted in the request headers @RequestHeader

query

: Complete automatic mapping and assignment directly with parameters @RequestParampath
: Submit data in the form of path variables @PathVariablebody
: Submitting in the form of a stream only supports POST (not commonly used) form
: Submitting in the form of a form only supports POST (not commonly used) Reference:

// 请求方法有多个请求参数 size， current
@ApiImplicitParams({
    @ApiImplicitParam(name="current", value="页码", required=true, paramType="path",dataType="int"),
    @ApiImplicitParam(name="size", value="每页记录数", required=true, paramType="path",dataType="int")
})
@ApiOperation("根据分类名称与状态查询分类列表接口")
@PostMapping("/search/{current}/{size}")
Result search(@RequestBody CategoryREQ req, @PathVariable int current, @PathVariable int size);

The above is the detailed content of How to use Swagger in SpringBoot. For more information, please follow other related articles on the PHP Chinese website!