Pourquoi avons-nous besoin d’une documentation appropriée pour notre projet d’API ?
C’est l’ère vers laquelle nous nous dirigeons rapidement avec des plateformes qui jouent le rôle principal dans nos activités sociales et économiques. Cela s’appelle simplement économie de plateforme. Ici, les API sont l’instance clé de la plate-forme. Habituellement, nous savons que de plus en plus d’entreprises adoptent le API première philosophie.
Si nous souhaitons atteindre certains objectifs commerciaux via la plate-forme, nous supposons avoir un bon projet d’API, mais si personne ne peut comprendre comment utiliser les API dans notre projet sans aucune documentation, alors notre projet sera inutile et ne sera pas en mesure d’atteindre notre objectif économique immédiatement. Pour cette raison, nous devons avoir documentation API lisible par l’homme pour notre projet.
Qu’est-ce que la documentation de l’API ?
La documentation de l’API est le plan technique lisible par l’homme de notre API. Il contient tous les principaux détails requis sur nos API, tels que les détails du chemin d’opération, les détails du type de corps des demandes, les détails des types de retour, les arguments pour l’API. En plus de cela, nous pouvons ajouter des exemples, y compris les entrées et sorties fictives de notre API dans la documentation de l’API. Nous pouvons simplement dire que la documentation de l’API est une structure complète de l’API dans votre projet.
Donc, si nous devons utiliser nos API par des développeurs d’API, nous devons leur fournir une documentation API bien compréhensible. La fourniture de la documentation de l’API conduira
-
Accroître la sensibilisation aux API dans le projet.
-
Améliorer l’adoption du projet par les utilisateurs (cela aidera nos développeurs internes à s’adapter rapidement à l’environnement du projet).
-
Faciliter la maintenance du projet en ajoutant et en modifiant des API.
Ce sont quelques avantages d’avoir une documentation API pour le projet.
De nos jours, la définition d’API la plus couramment utilisée est Spécification OpenAPI (anciennement Swagger). Je suppose que la plupart d’entre vous sont familiers avec OpenAPI, mais pour qui c’est nouveau d’avoir une introduction ici. Habituellement, nous nous habituons à l’utiliser car il est facile à comprendre, à utiliser et à concevoir les API de modèle.
« Swagger est une suite puissante mais facile à utiliser d’outils de développement d’API pour les équipes et les individus, permettant le développement tout au long du cycle de vie de l’API, de la conception et de la documentation au test et au déploiement. »
Génération de documents API
Si vous êtes un développeur qui suit le approche du code d’abord et est prêt à avoir votre documentation API à la fin des développements de l’API. Vous serez intéressant d’avoir une documentation outil de génération automatique pour votre projet plutôt que de passer du temps à rédiger manuellement votre documentation.
Aujourd’hui, il existe tellement d’outils de génération de code et de frameworks conçus pour convaincre les développeurs.
Si vous êtes un Développeur Ballerine alors tu peux essayer l’outil Ballerina OpenAPI pour générer votre Spécification OpenAPI aux API Ballerina.
Outillage Ballerina OpenAPI permettra aux utilisateurs de démarrer facilement le développement avec l’approche de code d’abord et l’approche de conception d’abord. Vous pouvez trouver plus de détails ici.
Comme condition préalable, nous devons installer une ballerine dans notre machine. Ici vous pouvez trouver des détails sur l’installation.
Maintenant, nous utiliserions le ballerina to openapi commande pour générer notre documentation API. Vous pouvez trouver les différentes options disponibles dans cette commande.
La ballerine à commande openapi
- Cela générera la définition OpenAPI de la version 3, y compris tous les détails de l’API dans le service ballerina avec YAML format.
bal openapi -i <ballerina-file>
- Si vous devez donner un emplacement pour le fichier de sortie, vous pouvez simplement ajouter le `-O` ou `–sortir` à la commande avec le répertoire cible.
bal openapi -i <ballerina-file> -o <output-file-path>
- Si vous avez besoin de votre définition OpenAPI avec JSON format, vous pouvez utiliser la commande ci-dessous pour cela.
bal openapi -i <ballerina-file> --json
- Normalement dans la Ballerine, on peut écrire plusieurs services à l’intérieur d’un dossier de ballerine. Pour la vue rapprochée, reportez-vous au exemple de code ci-dessous. Il contient deux services avec chemins de base `/utilisateur` et `/animal`, cette fois, nous pouvons sélectionner un service pour générer une documentation API en utilisant `—service` ou `-s` marque la commande ci-dessus. En dehors de cela, il générera une documentation API pour chaque service dans le fichier ballerina.
bal openapi -i <ballerina-file> --service /pet
Cette commande générera la documentation de l’API pour `/animaux`service.
Exemple de code ballerine
import ballerina/http;
listener http:Listener ep0 = new (80, config = {host: "http://petstore.openapi.io"});
type Pet record {
int petId;
string name;
string petType?;
};
service /pet on ep0 {
# Getting pet by givning petId
#
# + id - Pet Id
# + return - Details about pet
resource function get pet/[int id]() returns string {
// API process
return "hello";
}
# Getting all the pets on the list
#
# + offset - Number of retriving items
# + return - list of array
resource function get pets(int offset) returns Pet[] {
// Mock implementation
Pet p1 = {petId: 1, name: "Tommy", petType: "dog"};
Pet p2 = {petId: 2, name: "Rova", petType: "dog"};
Pet[] petArray = [p1, p2];
return petArray;
}
}
service /user on new http:Listener(9091) {
resource function get cachingBackEnd() returns @http:Cache {
maxAge: 5,
isPrivate: true,
privateFields: ["field1", "filed2"],
noCache: true,
noCacheFields: ["field03", "fields04"]
} string|http:Conflict {
// API implementation ...
return "Hello, World!!";
}
}
Ci-dessous la définition openAPI est définition openAPI générée pour ce qui précède `/animal de compagnie` service.
Définition OpenAPI générée
openapi: 3.0.1
info:
title: Pet
version: 1.0.0
servers:
- url: "{server}:{port}/hello"
variables:
server:
default: http://petstore.openapi.io
port:
default: "80"
paths:
/pet/{id}:
get:
summary: Getting pet by givning petId
operationId: "operation_get_/pet/{id}"
parameters:
- name: id
in: path
description: 'Pet Id '
required: true
schema:
type: integer
format: int32
responses:
"200":
description: Ok
content:
text/plain:
schema:
type: string
/pets:
get:
summary: Getting all the pets in the list
operationId: operation_get_/pets
parameters:
- name: offset
in: query
description: Number of retriving items
required: true
schema:
type: integer
format: int32
responses:
"200":
description: Ok
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pet'
components:
schemas:
Pet:
required:
- name
- petId
type: object
properties:
petId:
type: integer
format: int32
name:
type: string
petType:
type: string
Vous pouvez voir que cette définition OpenAPI générée comprend tous les détails des paramètres, les détails de la réponse, les détails du chemin et les détails de l’opération pour les fonctions de ressource ballerina qui se lient au service `/pet`.
Conclusion
Dans cet article, nous avons examiné pourquoi nous avons besoin de la documentation API pour nos API. Quant à savoir comment nous générons la documentation OpenAPI pour les API Ballerina. J’espère que vous aurez des idées ensoleillées sur le Outil CLI Ballerina OpenAPI pour votre génération de documents OpenAPI. Vous pouvez en savoir plus sur l’outil ici.
Au cours du prochain article, nous discuterons en profondeur de la cartographie des détails des fonctions de ressource de ballerine dans les sections de définition openAPI jusque-là, bon codage et bonne lecture.