Wie verwende ich Swagger zum Generieren einer API-Dokumentation?

Mit der rasanten Entwicklung von Webanwendungen wird die API-Dokumentation immer wichtiger. Die API-Dokumentation soll Entwicklern helfen, API-Nutzungsmethoden und -Parameter zu verstehen und so Zeit- und Ressourcenverschwendung zu reduzieren. Das manuelle Schreiben der API-Dokumentation kann jedoch umständlich und zeitaufwändig sein. Derzeit ist Swagger ein leistungsstarkes Tool für Entwickler. Swagger ist ein beliebtes API-Dokumentationstool, das automatisch lesbare und interaktive API-Dokumentation generieren kann. In diesem Artikel haben wir vorgestellt, wie man Swagger zum automatischen Generieren von API-Dokumentation verwendet.

Was ist Swagger?

Swagger ist eine Reihe von Open-Source-Tools, die Entwicklern beim Erstellen, Entwerfen, Beschreiben und Nutzen von RESTful-Webdiensten helfen. Mit Swagger können Sie API-Dokumentation im YAML- oder JSON-Format schreiben, die API-Operationen beschreibt und Schnittstellendokumentation generiert, die einfach zu lesen und zu interagieren ist.

Swagger unterstützt mehrere Programmiersprachen und Frameworks wie Java, C#, Python und Ruby. Es kann auch in viele bestehende API-Frameworks integriert werden, darunter unter anderem Spring, Express und Django.

Um Swagger zum Generieren von API-Dokumenten zu verwenden, müssen Sie zuerst Swagger UI installieren. Swagger UI ist eine interaktive API-Dokumentationswebsite, die unabhängig von der API ist und der Swagger-Spezifikation folgt. Es bietet eine schöne Schnittstelle zur Visualisierung der API-Dokumentation und unterstützt automatisierte Versuche von API-Aufrufen.

Schritt 1: Swagger konfigurieren

Um Swagger zu verwenden, müssen Sie zuerst das Swagger-Paket herunterladen, das von der Swagger-Website bezogen oder mit dem Abhängigkeitsmanager heruntergeladen werden kann.

Um die Swagger-API im Java Spring Boot-Projekt zu konfigurieren, müssen Sie die folgende Swagger-Abhängigkeit zur Maven-Abhängigkeit hinzufügen:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${springfox-swagger2.version}</version>
</dependency>
 
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox-swagger-ui.version}</version>
</dependency>

wobei ${springfox-swagger2.version} und ${springfox-swagger-ui.version} stellt die Swagger-Versionsnummer dar. Aktivieren Sie Swagger in der Konfigurationsdatei application.properties:

#开启swagger
swagger.enabled = true

Schritt 2: Swagger-Annotationen schreiben

Swagger verwendet Annotationen, um Vorgänge und Parameter in der API zu beschreiben. Fügen Sie Swagger-Anmerkungen zusätzlich zur API-Controller-Klasse und ihren Methoden hinzu, damit Swagger Dokumente korrekt analysieren, generieren und auf der Swagger-Benutzeroberfläche anzeigen kann.

Im Folgenden finden Sie einige Beispielanmerkungen:

1. @Api: wird zum Hinzufügen von Beschreibungsinformationen der API verwendet.

@Api(value="User",tags={"User 操作接口"})
@Controller
@RequestMapping("/users")
public class UserController {
    // ...
}

2. @ApiOperation: wird zum Hinzufügen von Beschreibungsinformationen von API-Operationen verwendet.

@ApiOperation(value = "获取用户列表", notes = "")
@GetMapping(value = "/list")
public Result getUserList() {
    List<User> userList = userService.listUser();
    return Result.success(userList);
}

3. @ApiParam: wird zum Hinzufügen verwendet API-Operationen Parameterbeschreibungsinformationen

@ApiOperation(value = "获取用户信息", notes = "根据url的id来获取用户详细信息")
@GetMapping(value = "/{id}")
public Result getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
    User user = userService.getUserById(id);
    return Result.success(user);
}

Schritt 3: Starten Sie die Anwendung und greifen Sie auf die Swagger-Benutzeroberfläche zu

Nachdem Sie das Schreiben der Swagger-Anmerkungen abgeschlossen haben, verwenden Sie einen Browser, um die Adresse der Swagger-Benutzeroberfläche zu öffnen. Es erstellt automatisch eine visuelle API-Dokumentation basierend auf Ihrer API.

Die Standardadresse der Swagger-Benutzeroberfläche lautet: http://localhost:8080/swagger-ui.html

Auf der Swagger-Benutzeroberfläche können Sie eine Übersicht über die API, Beschreibungen verschiedener API-Schnittstellen sowie Anforderungs- und Antwortparameter sehen Und etwas Testcode usw. Dies kann Entwicklern helfen, die API besser zu verstehen und zu nutzen.

Zusammenfassung

Swagger ist ein leistungsstarkes API-Dokumentationstool, das automatisch eine API-Dokumentation generieren kann, die einfach zu lesen und zu interagieren ist. Die Verwendung von Swagger kann die Effizienz und Qualität der API-Entwicklung verbessern und den Zeit- und Ressourcenaufwand für das manuelle Schreiben der API-Dokumentation reduzieren. Wenn Sie die oben genannten Schritte befolgen, können Sie Swagger ganz einfach zum automatischen Generieren von API-Dokumentation verwenden.

Das obige ist der detaillierte Inhalt vonWie verwende ich Swagger zum Generieren einer API-Dokumentation?. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!