Utiliser SwaggerUI pour implémenter la documentation en ligne de l'API dans Golang

Utiliser SwaggerUI pour implémenter la documentation en ligne de l'API dans Golang

Avec l'émergence de l'architecture d'application moderne, l'API (Application Programming Interface) est devenue le composant de base des applications Web modernes. Alors que le nombre d’API continue d’augmenter, la rédaction et la maintenance de la documentation des API sont devenues une tâche fastidieuse. Par conséquent, il est très nécessaire de simplifier le processus d’écriture et de maintenance de la documentation API. Swagger est une solution populaire qui fournit un puissant outil de documentation pour les API Web. Cet article explique comment utiliser SwaggerUI pour implémenter la documentation en ligne de l'API dans Golang.

Introduction à Swagger

Swagger est un ensemble d'outils de création d'API open source qui peuvent aider les développeurs à concevoir, créer, documenter et tester des API RESTful. Il comprend plusieurs outils tels que Swagger Editor, Swagger UI et Swagger Codegen.

Parmi eux, Swagger Editor est un éditeur basé sur un navigateur Web qui peut aider les développeurs à écrire et à modifier les spécifications Swagger UI est un outil qui peut restituer les spécifications Swagger dans les documents API et générer automatiquement des clients et des API côté serveur. code.

Utiliser SwaggerUI pour implémenter la documentation en ligne de l'API dans Golang

Golang est un langage de programmation très populaire. Ses avantages sont des performances de concurrence élevées et une faible surcharge. Il utilise des threads légers appelés Goroutines pour gérer la concurrence et prend en charge le recyclage automatique de la mémoire et le garbage collection. Dans Golang, vous pouvez utiliser la bibliothèque go-swagger pour implémenter la documentation en ligne de l'API.

1. Installer Swagger

Tout d'abord, vous devez installer Swagger, qui peut être installé via la commande suivante :

$ brew tap go-swagger/go-swagger
$ brew install go-swagger

2. Initialiser un projet Golang

Ensuite, vous devez initialiser un projet Golang sur votre ordinateur local. Créez un projet Golang nommé Go-Swagger-API sur votre machine locale à l'aide de la commande suivante :

$ mkdir Go-Swagger-API 
$ cd Go-Swagger-API 
$ go mod init Go-Swagger-API 

3. Créer une définition d'API

Afin de créer une définition d'API, vous devez créer un fichier YAML et définir les paramètres de l'API dans il. Dans cet exemple, vous pouvez créer un fichier nommé pets.yaml et y ajouter le code suivant :

swagger: "2.0"
info:
  version: 1.0.0
  title: Petstore API 
produces:
- application/json
paths:
  /pets:
    get:
      summary: List all pets 
      responses:
        200:
          description: OK
        500:
          description: Internal Server Error
    post:
      summary: Add a new pet 
      parameters:
        - in: body
          name: body
          schema:
            "$ref": "#/definitions/pet"
          required: true
      responses:
        201:
          description: Created
        500:
          description: Internal Server Error

definitions:
  pet:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      tag:
        type: string

4. Générer un framework de serveur API

Ensuite, vous devez utiliser l'outil go-swagger pour générer le code Le générateur. générera automatiquement du code en utilisant la configuration définie à l’étape précédente. Entrez la commande suivante dans le terminal :

$ swagger generate server -A Go-Swagger-API -f pets.yaml

Cette commande générera le framework côté serveur basé sur la définition dans le fichier YAML.

5. Démarrez le serveur API

Ensuite, vous devez démarrer le serveur API et vérifier qu'il fonctionne correctement. Entrez la commande suivante dans le terminal :

$ cd cmd/go-swagger-api-server/
$ go run main.go

Le résultat devrait ressembler à ce qui suit :

Serving Go-Swagger-API at http://127.0.0.1:8080 

Vous devriez maintenant pouvoir accéder à l'URL suivante dans votre navigateur Web pour vérifier que l'API fonctionne : http : //127.0.0.1 :8080/animaux. http://127.0.0.1:8080/pets。

6. 集成SwaggerUI

最后一步是在API服务器中集成SwaggerUI。首先，在项目的根目录下创建一个名为swagger-ui的目录，并在其中下载SwaggerUI，可以通过下面的命令来实现：

$ mkdir swagger-ui && cd swagger-ui && wget https://github.com/swagger-api/swagger-ui/archive/v3.32.3.tar.gz && tar xfz v3.32.3.tar.gz --strip-components=1 && rm v3.32.3.tar.gz

接下来，在API服务器的main.go文件中添加以下代码：

// Setup the SwaggerUI middleware
swaggerUI := http.FileServer(http.Dir("./swagger-ui/dist"))
r.PathPrefix("/docs").Handler(http.StripPrefix("/docs", swaggerUI))

此代码将SwaggerUI中的dist目录作为静态资源文件公开，用于呈现实际的SwaggerUI。

现在，可以在浏览器中访问以下URL以查看自动生成的API文档：http://localhost:8080/docs/index.html

Intégrer SwaggerUI

La dernière étape consiste à intégrer SwaggerUI dans le serveur API. Tout d'abord, créez un répertoire nommé swagger-ui dans le répertoire racine du projet et téléchargez-y SwaggerUI. Cela peut être réalisé en exécutant la commande suivante :

rrreee🎜 Ensuite, ajoutez le code suivant dans le fichier main.go de l'API. server :🎜rrreee🎜Ce code expose le répertoire dist dans SwaggerUI en tant que fichier de ressources statiques pour le rendu du SwaggerUI réel. 🎜🎜Maintenant, vous pouvez visiter l'URL suivante dans votre navigateur pour afficher la documentation de l'API générée automatiquement : http://localhost:8080/docs/index.html. 🎜🎜Conclusion🎜🎜Il n'est pas difficile d'utiliser SwaggerUI pour implémenter la documentation en ligne de l'API dans Golang, ce qui apporte une grande commodité à la rédaction et à la maintenance de la documentation de l'API. En utilisant Swagger, la documentation peut être automatiquement générée pour l'API, et les ingénieurs back-end et front-end peuvent rapidement comprendre l'interface de l'API. Cela simplifie considérablement le processus de développement, de test et de documentation des API, permettant aux développeurs de se concentrer davantage sur la mise en œuvre de la logique métier. 🎜

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!