Verwenden Sie Spring Boot und Swagger, um eine RESTful-API-Dokumentation zu erstellen

In der heutigen Webentwicklung ist die RESTful API für Entwickler zu einer sehr beliebten Methode zum Erstellen von Websites und Anwendungen geworden. Mithilfe der RESTful API können Entwickler klare APIs erstellen, um bequemer mit anderen Anwendungen oder Diensten zu interagieren. Um diese APIs besser verwalten und warten zu können, sind auch das Schreiben und Verwalten von Dokumenten zu einem sehr wichtigen Bestandteil geworden.

Spring Boot ist ein Framework zum schnellen Erstellen von Java-Anwendungen, das einfach, schnell und leicht zu erweitern ist. Swagger ist ein Tool, das speziell zum Entwerfen, Erstellen und Dokumentieren von RESTful-APIs verwendet wird. Es kann schnell RESTful-API-Dokumente generieren und automatisch Beispielflüsse von API-Anfragen und -Antworten generieren.

In diesem Artikel erfahren Sie, wie Sie Spring Boot und Swagger zum Erstellen von RESTful-API-Dokumenten verwenden.

1. Erstellen Sie ein Spring Boot-Projekt

Zuerst müssen wir Spring Initializr verwenden, um ein Spring Boot-Projekt zu erstellen, das über https://start.spring.io/ erstellt werden kann. Hier wählen wir die beiden Abhängigkeiten Web und Swagger 2 aus. Nachdem die Erstellung abgeschlossen ist, importieren wir das Projekt in die integrierte Entwicklungsumgebung und fügen die Swagger-Abhängigkeit in pom hinzu.

Wir fügen dem Controller eine Methode hinzu:

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

Es ist zu beachten, dass nicht nur die Annotation @RestController zur Klasse hinzugefügt werden muss, sondern auch die Annotation @Api verwendet werden muss, um die Rolle dieses Controllers zu beschreiben.

Dekompilierter Inhalt:

@RestController
public class NumberController {
 
   @ApiOperation(value = "Generate a random number between 1 and 100")
   @RequestMapping(value = "/generateNumber", method = RequestMethod.GET)
   public ResponseEntity<Integer> generateNumber() {
       Random random = new Random();
       int randomNumber = random.nextInt(100) + 1;
       return ResponseEntity.ok(randomNumber);
   }
}

3. Swagger konfigurieren

Nach Abschluss der Entwicklung des entsprechenden Controllers müssen wir Swagger konfigurieren. Fügen Sie die Swagger-bezogene Konfiguration zur Spring Boot-Konfigurationsdatei application.properties hinzu.

package com.example.demo.controller;

import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import java.util.Random;

@RestController
public class NumberController
{

    public NumberController()
    {
    }

    @ApiOperation(value="Generate a random number between 1 and 100")
    @RequestMapping(value="/generateNumber", method=RequestMethod.GET)
    public ResponseEntity generateNumber()
    {
        Random random = new Random();
        int randomNumber = random.nextInt(100) + 1;
        return ResponseEntity.ok(new Integer(randomNumber));
    }
}

Annotationsbeschreibung:

@Api: Wird zur Beschreibung der Rolle des Controllers verwendet, ähnlich den Annotationen @Controller und @RequestMapping in Spring MVC.

@ApiIgnore: wird für ignorierte APIs verwendet und wird nicht in der generierten API-Dokumentation angezeigt.

@ApiOperation: Wird zur Beschreibung spezifischer API-Operationen verwendet, einschließlich Methodenname, Anforderungsmethode, Anforderungsparameter, Rückgabeobjekt und anderen Informationen, die auf der Methode oder Klasse platziert werden können.

@ApiImplicitParam: wird zur Beschreibung von Anforderungsparametern verwendet, einschließlich Parametername, Parametertyp, Notwendigkeit und anderen Informationen.

@ApiModel: wird zur Beschreibung von JavaBean-Klassen verwendet.

@ApiParam: wird zur Beschreibung von Parameterinformationen verwendet.

@ApiResponses: Wird zur Beschreibung von API-Antworten verwendet, einschließlich HTTP-Statuscode, Antwortdaten und anderen Informationen.

@ApiProperty: Wird zur Beschreibung der Eigenschaftsinformationen der JavaBean-Klasse verwendet.

4. Sehen Sie sich die API-Dokumentation an

Nach Abschluss der obigen Konfiguration starten wir die Spring Boot-Anwendung und besuchen http://localhost:8080/swagger-ui.html. Wir können die generierte API-Dokumentation im Browser anzeigen. Hier können wir die detaillierten Informationen der gerade geschriebenen API anzeigen, einschließlich Anforderungsmethode, Anforderungsparameter, Rückgabeergebnisse usw. Gleichzeitig kann Swagger auch einen Beispielstrom von Anfragen und Antworten generieren, um Entwicklern das Referenzieren und Testen zu erleichtern.

Hier verwenden wir Spring Boot und Swagger, um eine RESTful-API-Dokumentation zu erstellen. Mit dieser Methode können Entwickler ihre eigenen API-Dokumente schneller erstellen und verwalten und so die Entwicklungseffizienz und Wartbarkeit verbessern.

Das obige ist der detaillierte Inhalt vonVerwenden Sie Spring Boot und Swagger, um eine RESTful-API-Dokumentation zu erstellen. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!