Exemple de documentation Swagger

Voici un exemple complet de document Swagger, qui est une spécification détaillée d'une API de système de gestion des utilisateurs.

Ce document décrit l'API d'un système de gestion des utilisateurs, y compris les informations de base des utilisateurs, les services d'authentification, les modèles de données, etc.

Cette API suit le style RESTful et utilise le format JSON pour l'échange de données.

Vous pouvez utiliser Swagger Editor pour tester votre document en ligne. Adresse en ligne :https://editor.swagger.io/. Copiez et collez simplement votre YAML ou JSON dans l'éditeur, et le panneau de droite affichera la documentation API visualisée.

Exemple

openapi: 3.0.0
informations:
title:Ma première API
description: |
Ceci est un exemple simple de document API qui démontre les fonctions de base d'un système de gestion des utilisateurs.
Y compris les opérations de requête, de création, de mise à jour et de suppression des utilisateurs.
version: 1.0.0
contact:
name:Équipe de support API
email: support@example.com
url: https://www.example.com/support
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html

servers:
- url: https://api.example.com/v1
description:Environnement de production
- url: https://staging-api.example.com/v1
description:Environnement de préproduction
- url: https://dev-api.example.com/v1
description:Environnement de développement

tags:
- name:Utilisateur
description:Opérations liées à la gestion des utilisateurs
- name:Authentification
description:Opérations liées à l'authentification

chemins:
/users:
get:
tags:
-Utilisateur
summary:Obtenir la liste de tous les utilisateurs
description:Renvoie toutes les informations des utilisateurs du système, avec prise en charge de la pagination et du filtrage
operationId: getUsers
parameters:
- name: limit
in: query
description:Nombre maximum de résultats à renvoyer
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 100
default: 20
- name: offset
in: query
description:Décalage de pagination
required: false
schema:
type: integer
format: int32
minimum: 0
default: 0
- name: status
in: query
description:Filtrer par statut d'utilisateur
required: false
schema:
type: string
enum: [active, inactive, banned]
responses:
'200':
description:Liste des utilisateurs récupérée avec succès
content:
application/json:
schema:
type: object
properties:
total:
type: integer
description:Nombre total d'utilisateurs
users:
type: array
items:
$ref: '#/components/schemas/User'
exemple:
total: 2
users:
- id: 1
username: "john_doe"
email: "[email protected]"
status: "active"
createdAt: "2023-05-01T12:00:00Z"
- id: 2
username: "jane_smith"
email: "[email protected]"
status: "active"
createdAt: "2023-05-02T14:30:00Z"
'400':
description:Requête invalide
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/UnauthorizedError'
sécurité:
- bearerAuth: []

post:
tags:
-Utilisateur
summary:Créer un nouvel utilisateur
description:Créer un nouvel utilisateur dans le système
operationId: createUser
requestBody:
description:Informations sur l'utilisateur
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
exemple:
username: "new_user"
email: "[email protected]"
password: "securePassword123"
responses:
'201':
description:Utilisateur créé avec succès
content:
application/json:
schema:
$ref: '#/components/schemas/User'
exemple:
id: 3
username: "new_user"
email: "[email protected]"
status: "active"
createdAt: "2023-05-10T09:15:00Z"
'400':
description:Requête invalide
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
exemple:
code: 400
message: "Format d'e-mail invalide"
'409':
description:Conflit de ressource
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
exemple:
code: 409
message: "Le nom d'utilisateur existe déjà"
'401':
$ref: '#/components/responses/UnauthorizedError'
sécurité:
- bearerAuth: []

/users/{userId}:
parameters:
- name: userId
in: path
description:ID utilisateur
required: true
schema:
type: integer
format: int64

get:
tags:
-Utilisateur
summary:Obtenir un utilisateur spécifique
description:Obtenir des informations détaillées sur un utilisateur spécifique par ID
operationId: getUserById
responses:
'200':
description:Informations utilisateur récupérées avec succès
content:
application/json:
schema:
$ref: '#/components/schemas/UserDetail'
exemple:
id: 1
username: "john_doe"
email: "[email protected]"
firstName: "John"
lastName: "Doe"
phone: "+1234567890"
status: "active"
createdAt: "2023-05-01T12:00:00Z"
lastLogin: "2023-05-10T08:30:00Z"
'404':
description:Utilisateur introuvable
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
exemple:
code: 404
message: "Utilisateur introuvable"
'401':
$ref: '#/components/responses/UnauthorizedError'
sécurité:
- bearerAuth: []

put:
tags:
-Utilisateur
summary:Mettre à jour les informations utilisateur
description:Mettre à jour les informations d'un utilisateur spécifique
operationId: updateUser
requestBody:
description:Informations utilisateur mises à jour
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUser'
exemple:
firstName: "Jonathan"
lastName: "Doe"
phone: "+1987654321"
responses:
'200':
description:Informations utilisateur mises à jour avec succès
content:
application/json:
schema:
$ref: '#/components/schemas/UserDetail'
'400':
description:Requête invalide
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description:Utilisateur introuvable
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/UnauthorizedError'
sécurité:
- bearerAuth: []

effacement:
tags:
-Utilisateur
summary:Supprimer l'utilisateur
description:Supprimer un utilisateur spécifique du système
operationId: deleteUser
responses:
'204':
description:Utilisateur supprimé avec succès
'404':
description:Utilisateur introuvable
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/UnauthorizedError'
sécurité:
- bearerAuth: []

/auth/login:
post:
tags:
-Authentification
summary:Connexion de l'utilisateur
description:L'utilisateur se connecte et obtient un jeton d'accès
operationId: login
requestBody:
description:Identifiants de connexion
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
description:Nom d'utilisateur
mot de passe:
type: string
format: password
description:Mot de passe
required:
- username
- mot de passe
exemple:
username: "john_doe"
password: "password123"
responses:
'200':
description:Connexion réussie
content:
application/json:
schema:
type: object
properties:
accessToken:
type: string
description:Jeton d'accès JWT
tokenType:
type: string
description:Type de jeton
expiresIn:
type: integer
description:Durée d'expiration du jeton (secondes)
exemple:
accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
tokenType: "Bearer"
expiresIn: 3600
'401':
description:Échec de la connexion
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
exemple:
code: 401
message: "Nom d'utilisateur ou mot de passe incorrect"

/auth/register:
post:
tags:
-Authentification
summary:Inscription d'un utilisateur
description:Enregistrer un nouvel utilisateur et obtenir un jeton d'accès
operationId: register
requestBody:
description:Informations d'inscription
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
responses:
'201':
description:Inscription réussie
content:
application/json:
schema:
type: object
properties:
user:
$ref: '#/components/schemas/User'
accessToken:
type: string
description:Jeton d'accès JWT
exemple:
user:
id: 3
username: "new_user"
email: "[email protected]"
status: "active"
createdAt: "2023-05-10T09:15:00Z"
accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
'400':
description:Requête invalide
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description:L'utilisateur existe déjà
content:
application/json:
schema:
$ref: '#/components/schemas/Error'

components:
schemas:
Utilisateur:
type: object
properties:
id:
type: integer
format: int64
description:Identifiant unique de l'utilisateur
username:
type: string
description:Nom d'utilisateur
email:
type: string
format: email
description:E-mail de l'utilisateur
status:
type: string
enum: [active, inactive, banned]
description:Statut de l'utilisateur
createdAt:
type: string
format: date-time
description:Date de création
required:
- id
- username
- email
- status

UserDetail:
allOf:
- $ref: '#/components/schemas/User'
- type: object
properties:
firstName:
type: string
description:Prénom
lastName:
type: string
description:Nom
phone:
type: string
description:Numéro de téléphone
lastLogin:
type: string
format: date-time
description:Date de dernière connexion

NewUser:
type: object
properties:
username:
type: string
description:Nom d'utilisateur
minLength: 3
maxLength: 50
email:
type: string
format: email
description:E-mail de l'utilisateur
mot de passe:
type: string
format: password
description:Mot de passe utilisateur
minLength: 8
maxLength: 100
firstName:
type: string
description:Prénom
lastName:
type: string
description:Nom
phone:
type: string
description:Numéro de téléphone
required:
- username
- email
- mot de passe

UpdateUser:
type: object
properties:
email:
type: string
format: email
description:E-mail de l'utilisateur
firstName:
type: string
description:Prénom
lastName:
type: string
description:Nom
phone:
type: string
description:Numéro de téléphone
mot de passe:
type: string
format: password
description:Nouveau mot de passe (si changement)
minLength: 8
maxLength: 100

Erreur:
type: object
properties:
code:
type: integer
format: int32
description:Code d'erreur
message:
type: string
description:Message d'erreur
required:
- code
- message

responses:
UnauthorizedError:
description:Le jeton d'accès est manquant ou invalide
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
exemple:
code: 401
message: "Accès non autorisé"

securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description:S'authentifier à l'aide d'un jeton JWT Bearer

sécurité:
- bearerAuth: []

Voici les principaux composants du document :

1. Section Informations de base

Titre et description de l'API: Fonctions de base du système de gestion des utilisateurs
Informations sur la version：1.0.0
Informations de contact: Informations de contact de l'équipe d'assistance de l'API
Licence：Apache 2.0

2. Configuration du serveur

Environnement de production
Environnement de préproduction
Environnement de développement

3. Classification des tags de l'API

Opérations liées aux utilisateurs
Opérations liées à l'authentification

4. Chemins et opérations

Cette API inclut les points de terminaison suivants:

Gestion des utilisateurs

GET /users- Obtenir la liste de tous les utilisateurs (prend en charge la pagination et le filtrage)
POST /users- Créer un nouvel utilisateur
GET /users/{userId}- Obtenir les détails d'un utilisateur spécifique
PUT /users/{userId}- Mettre à jour les informations de l'utilisateur
DELETE /users/{userId}- Supprimer l'utilisateur

Service d'authentification

POST /auth/login- Connexion de l'utilisateur
POST /auth/register- Inscription de l'utilisateur

5. Modèles de données

User- Informations de base sur l'utilisateur
UserDetail- Informations détaillées sur l'utilisateur
NewUser- Corps de la requête pour créer un utilisateur
UpdateUser- Corps de la requête pour la mise à jour d'un utilisateur
Error- Réponse d'erreur

6. Définitions de sécurité

Utilisez un jeton JWT Bearer pour l'authentification de l'API.

Ce document suit la spécification OpenAPI 3.0.0 et inclut des paramètres de requête complets, les codes d'état de réponse, les définitions de modèles de données et des exemples de valeurs. Vous pouvez copier ce document YAML dans Swagger Editor pour voir la visualisation, ou l'intégrer dans votre projet.

Ce document peut servir de base au développement de votre API RESTful et peut être étendu et amélioré au fur et à mesure que le projet évolue.

Autres extensions