So verwenden Sie das integrierte Schnittstellenverwaltungstool Swagger von SpringBoot

1. Einführung in Swagger

Swagger ist eine Reihe von RESTful-API-Tools, mit denen Sie ein interaktives Dokument des Projekts, die automatische Generierung von Client-SDKs und andere Funktionen erhalten können.

Swaggers Ziel ist es, eine standardisierte, sprachunabhängige Schnittstelle für REST-APIs zu definieren, sodass Personen und Computer den Quellcode oder die Dokumente nicht sehen oder die Netzwerkverkehrserkennung nicht passieren können Entdecken und verstehen Sie die Funktionen verschiedener Dienste. Wenn Dienste über Swagger definiert werden, können Verbraucher mit einem kleinen Umfang an Implementierungslogik mit Remote-Diensten interagieren.

2. Springboot integriert Swagger

Das Konzept der Verwendung von Spring Boot zur Integration von Swagger besteht darin, Anmerkungen zu verwenden, um die Informationen zu markieren, die im API-Dokument und in Swagger angezeigt werden müssen Markieren Sie Anmerkungen entsprechend dem Projekt, um die entsprechende API-Dokumentation zu generieren. Swagger ist als das beliebteste API-Tool der Welt bekannt. Es bietet eine Komplettlösung für die API-Dokumentenverwaltung. Hier werden die am häufigsten verwendeten Anpassungsinhalte erläutert.

1. Swagger-Koordinaten hinzufügen

Die Spring Boot-Integration mit Swagger 3 ist sehr einfach. Sie müssen nur Abhängigkeiten einführen und eine Grundkonfiguration durchführen.

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

2. Swagger Helloword-Implementierung

2.1. Erstellen Sie ein Springboot-Projekt

Fügen Sie die Annotation @EnableOpenApi zur Startup-Klasse hinzu, um die Swagger-API-Dokumentfunktion zu aktivieren# 🎜🎜#

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;

@SpringBootApplication
@EnableOpenApi  //启动swagger api文档注解
public class SpringBootWithSwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootWithSwaggerApplication.class, args);
    }

}

2.2. Schreiben Sie eine Schnittstelle

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

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
public class SwaggerController {
    @GetMapping ("hello")
    public String hello(String params) {
        return "hello swagger"+" param为:"+params;
    }
}

2.3. Zugriffsadresse

http://localhost:8080/swagger-ui/index.html

# 🎜🎜 #

3. Häufig verwendete Konfigurationsanmerkungen

Swagger verwendet Anmerkungen, um anzugeben, dass die Schnittstelle Dokumente generiert, einschließlich Schnittstellenname, Anforderungsmethode, Parameter, Rückgabeinformationen usw. # 🎜🎜## 🎜🎜#1,

Api

Annotation und

ApiOperation

Annotation#🎜 🎜# @Api# 🎜 🎜#

• wird für die Klasse verwendet, um anzugeben, dass es sich um eine Swagger-Ressource handelt, die zwei Attribute hat: Wert und Tags. Die generierten API-Dokumente werden nach Tags klassifiziert. Um es ganz klar auszudrücken: Die von allen Schnittstellen in diesem Controller generierten Schnittstellendokumente befinden sich unter der Tag-Liste generiert werden. Liste, jede Liste zeigt alle Schnittstellen an # @ApiOperation

wird für Methoden verwendet, um die Operation einer http-Anfrage darzustellen

语法:
  @Api(tags = "用户操作")
  或
  @Api(tags = {"用户操作","用户操作2"})

Fall: Verwenden Sie @Api und @ ApiOperation generiert API-Dokumente

语法:
    @ApiOperation(value = "", 
                  notes = "", 
                  response = )
属性说明：
  value：方法说明标题
  notes：方法详细描述
  response：方法返回值类型

2,

ApiImplicitParams
• Anmerkungen und

  ApiImplicitParam

  #🎜 🎜 #@ApiImplicitParams # 🎜🎜# Anmerkungen und
@ApiImplicitParam

werden verwendet, um Nicht-Objekt-Parameter in Methoden zu beschreiben (wird verwendet, wenn Parameter an einfache Typen gebunden sind).

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
@Api(tags = {"操作用户"})
public class SwaggerController {
    @GetMapping ("hello")
    @ApiOperation(value = "swagger请求",notes = "阿水的第一个swagger请求",response = String.class)
    public String hello(String params) {
        return "hello swagger"+" param为:"+params;
    }
}

Hinweis: @ApiImplicitParam Das Namensattribut sollte den Wert von @RequestParam oder @PathVariable widerspiegeln.

Fall: Verwenden Sie die Annotation @ApiImplicitParams und @ApiImplicitParam, um Methodenparameter zu beschreiben. 🎜 🎜#

@ApiModel wird für Entitätsklassen verwendet, um die Klasse zu beschreiben, und wird für Parameterempfangsanweisungen in der Entitätsklasse verwendet.

语法:
@ApiImplicitParams(value = {
     @ApiImplicitParam(name="", value = "", type = "", required = true, paramType = "", defaultValue  = "")
})

属性说明：
    name:形参名称
    value:形参的说明文字
    type:形参类型
    required:该参数是否必须  true|false
    paramType: 用于描述参数是以何种方式传递到 Controller 的，它的值常见有： path, query, body 和 header 
        path 表示参数是『嵌在』路径中的，它和 @PathVariable 参数注解遥相呼应；
    	query 表示参数是以 query string 的形式传递到后台的（无论是 get 请求携带在 url 中，还是 post 请求携带在请求体中），它和 @RequestParam 参数注解遥相呼应；
    	header 表示参数是『藏在』请求头中传递到后台的，它和 @RequestHeader 参数注解遥相呼应的。
    	form 不常用.
    defaultValue :参数默认值

4, ApiResponse und ApiResponses@ApiResponses-Annotation und @ApiResponse-Annotation befinden sich in der Controller-Methode, um die Antwort der HTTP-Anfrage zu beschreiben

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
@Api(tags = {"操作用户"})
public class SwaggerController {
    @GetMapping ("hello")
    @ApiOperation(value = "swagger请求",notes = "阿水的第一个swagger请求",response = String.class)
    @ApiImplicitParams(value ={
            @ApiImplicitParam(name="param1",
                    value = "参数名1",
                    type = "String",
                    required = true,
                    paramType = "query",
                    defaultValue  = "阿水所想的默认值1" ),
            @ApiImplicitParam(name="param2",
                    value = "参数名2",
                    type = "String",
                    required = true,
                    paramType = "query",
                    defaultValue  = "阿水所想的默认值2" )
    })
    public String hello(String param1,String param2) {
        return "hello swagger"+" param1为:"+param1+"param2为"+param2;
    }
}

5. Erstellen Sie die SwaggerConfig-Konfigurationsklasse

Fügen Sie zwei Methoden in SwaggerConfig hinzu: (Eine Methode dient dazu, zusätzliche Vorbereitungen für die andere Methode zu treffen)

#🎜🎜 Die #api()-Methode verwendet @Bean, wird beim Start initialisiert und gibt das Instanz-Docket (Swagger-API-Zusammenfassungsobjekt) zurück. Hier ist zu beachten, dass .apis(RequestHandlerSelectors.basePackage("xxx.yyy.zzz")) ist. Gibt den Bedarf an. Der gescannte Paketpfad. Nur die Controller-Klasse unter diesem Pfad generiert automatisch das Swagger-API-Dokument. Die Konfiguration der

@ApiModel("用户类")
@Data
public class Users {

    @ApiModelProperty(value = "编码：主键")
    private Integer id;

    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "密码")
    private String password;

}

apiInfo()-Methode ist relativ wichtig. Zu den grundlegenden Informationen, die auf der Hauptkonfigurationsseite angezeigt werden, gehören Titel, Beschreibung, Version, Nutzungsbedingungen usw. Wenn Sie den Quellcode der ApiInfo-Klasse überprüfen , Sie werden auch feststellen, dass es Lizenzen und mehr unterstützt , ersetzen Sie UI

Der gesamte oben beschriebene Prozess wurde abgeschlossen, aber viele Leute mögen die generierte Schnittstellendokumentseite nicht, weil sie der Meinung sind, dass sie nicht den Nutzungsgewohnheiten der Chinesen entspricht Bereitstellung weiterer UI-Testseiten. Diese Seite wird immer noch häufig verwendet.

Importieren Sie die folgenden Abhängigkeiten, starten Sie das Projekt neu und greifen Sie auf die Adresse zu: http://localhost:8080/doc.html

• /**
       * 添加用户
       *
       * @param user
       * @return
       */
      @PostMapping("/add")
      @ApiOperation(value = "添加用户",notes = "添加用户信息",response = ResponseResult.class)
      @ApiResponses({ @ApiResponse(code = 200, message = "添加成功", response = ResponseResult.class),
              	    @ApiResponse(code = 500, message = "添加失败", response = ResponseResult.class) })
      public ResponseResult<Void> addUser(@RequestBody User user) {
          //获得生成的加密盐
          user.setSalt(SaltUtils.getSalt());
          int n = userService.addUser(user);
          if (n > 0) {
              return new ResponseResult<Void>(200, "添加成功");
          }
          return new ResponseResult<Void>(500, "添加失败");
      }

Das obige ist der detaillierte Inhalt vonSo verwenden Sie das integrierte Schnittstellenverwaltungstool Swagger von SpringBoot. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!