Fonctionnalités avancées de Swagger
Utilisation de components pour réutiliser des définitions
Réutilisation du schéma (modèle de données)
components vous permettent de définir des éléments qui peuvent être réutilisés dans toute la documentation de l'API, ce qui réduit la duplication et garantit la cohérence :
Exemple
components:
schemas:
Utilisateur:
type: object
properties:
id:
type: integer
format: int64
username:
type: string
email:
type: string
schemas:
Utilisateur:
type: object
properties:
id:
type: integer
format: int64
username:
type: string
email:
type: string
Méthode de référence :
Exemple
chemins:
/users/{id}:
get:
responses:
'200':
description:Informations utilisateur
content:
application/json:
schema:
$ref: '#/components/schemas/User'
/users/{id}:
get:
responses:
'200':
description:Informations utilisateur
content:
application/json:
schema:
$ref: '#/components/schemas/User'
Réutilisation des paramètres (paramètres communs)
Définir les paramètres communs :
Exemple
components:
parameters:
PageParam:
name: page
in: query
schema:
type: integer
default: 1
description:Numéro de page
LimitParam:
name: limit
in: query
schema:
type: integer
default: 10
description:Enregistrements par page
parameters:
PageParam:
name: page
in: query
schema:
type: integer
default: 1
description:Numéro de page
LimitParam:
name: limit
in: query
schema:
type: integer
default: 10
description:Enregistrements par page
Méthode de référence :
Exemple
chemins:
/products:
get:
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/LimitParam'
/products:
get:
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/LimitParam'
Réutilisation des réponses (réponses communes)
Définir les réponses standard :
Exemple
components:
responses:
NotFound:
description:Ressource introuvable
content:
application/json:
schema:
type: object
properties:
code:
type: integer
exemple: 404
message:
type: string
example: "La ressource n'existe pas"
BadRequest:
description:Erreur de paramètre de requête
content:
application/json:
schema:
type: object
properties:
code:
type: integer
exemple: 400
message:
type: string
responses:
NotFound:
description:Ressource introuvable
content:
application/json:
schema:
type: object
properties:
code:
type: integer
exemple: 404
message:
type: string
example: "La ressource n'existe pas"
BadRequest:
description:Erreur de paramètre de requête
content:
application/json:
schema:
type: object
properties:
code:
type: integer
exemple: 400
message:
type: string
Méthode de référence :
Exemple
chemins:
/users/{id}:
get:
responses:
'200':
description:Succès
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
$ref: '#/components/responses/NotFound'
'400':
$ref: '#/components/responses/BadRequest'
/users/{id}:
get:
responses:
'200':
description:Succès
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
$ref: '#/components/responses/NotFound'
'400':
$ref: '#/components/responses/BadRequest'
Gestion des versions de l'API
Distinguer les versions via les serveurs
Exemple
servers:
- url: https://api.example.com/v1
description: API v1
- url: https://api.example.com/v2
description: API v2
- url: https://api.example.com/v1
description: API v1
- url: https://api.example.com/v2
description: API v2
Distinguer les versions via le chemin
Exemple
chemins:
/v1/users:
get:
# v1 interface utilisateur...
/v2/users:
get:
# v2 interface utilisateur...
/v1/users:
get:
# v1 interface utilisateur...
/v2/users:
get:
# v2 interface utilisateur...
Distinguer les versions via les en-têtes de requête
Exemple
chemins:
/users:
get:
parameters:
- name: api-version
in: header
required: true
schema:
type: string
enum: ['1.0', '2.0']
/users:
get:
parameters:
- name: api-version
in: header
required: true
schema:
type: string
enum: ['1.0', '2.0']
Simulation de données factices
Utiliser des exemples pour définir des données d'exemple
Définir des exemples dans la réponse :
Exemple
chemins:
/users:
get:
responses:
'200':
description:Liste d'utilisateurs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
examples:
userList:
summary:Exemple de liste d'utilisateurs
value:
- id: 1
username: "user1"
email: "[email protected]"
- id: 2
username: "user2"
email: "[email protected]"
/users:
get:
responses:
'200':
description:Liste d'utilisateurs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
examples:
userList:
summary:Exemple de liste d'utilisateurs
value:
- id: 1
username: "user1"
email: "[email protected]"
- id: 2
username: "user2"
email: "[email protected]"
Utilisation de la fonctionnalité Mock de Swagger UI
Swagger UI intègre un serveur mock qui peut générer des réponses simulées en fonction de votre définition OpenAPI.
Configurer mockServer dans Swagger UI :
Exemple
SwaggerUI({
url: "https://petstore.swagger.io/v2/swagger.json",
dom_id: '#swagger-ui',
presets: [
SwaggerUI.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUI.plugins.MockPlugin
],
mockImplementations: {
'/users': {
get: () => ({
status: 200,
body: [
{ id: 1, name: "Utilisateur Test 1" },
{ id: 2, name: "Utilisateur Test 2" }
]
})
}
}
})
url: "https://petstore.swagger.io/v2/swagger.json",
dom_id: '#swagger-ui',
presets: [
SwaggerUI.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUI.plugins.MockPlugin
],
mockImplementations: {
'/users': {
get: () => ({
status: 200,
body: [
{ id: 1, name: "Utilisateur Test 1" },
{ id: 2, name: "Utilisateur Test 2" }
]
})
}
}
})
Utilisation de services Mock tiers
- Prism : serveur mock OpenAPI
- Mockoon : un outil d'API mock qui peut s'intégrer à Swagger
- Postman : fournit des fonctionnalités de serveur mock
Configuration de sécurité avancée
Définir plusieurs méthodes d'authentification :
Exemple
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
apiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
OAuth2:
type: oauth2
flows:
implicit:
authorizationUrl: https://example.com/oauth/authorize
scopes:
read:Permission de lecture
write:Permission d'écriture
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
apiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
OAuth2:
type: oauth2
flows:
implicit:
authorizationUrl: https://example.com/oauth/authorize
scopes:
read:Permission de lecture
write:Permission d'écriture
Appliquer les définitions de sécurité :
Exemple
sécurité:
- bearerAuth: []
- apiKeyAuth: []
chemins:
/users:
get:
sécurité:
- OAuth2: [read]
- bearerAuth: []
- apiKeyAuth: []
chemins:
/users:
get:
sécurité:
- OAuth2: [read]
Séparation et organisation des documents
Utiliser$refpour référencer des fichiers externes :
Exemple
chemins:
/users:
$ref: './paths/users.yaml'
/products:
$ref: './paths/products.yaml'
components:
schemas:
Utilisateur:
$ref: './schemas/user.yaml'
/users:
$ref: './paths/users.yaml'
/products:
$ref: './paths/products.yaml'
components:
schemas:
Utilisateur:
$ref: './schemas/user.yaml'
Balises et regroupement
Utilisez des balises pour organiser les points de terminaison d'API :
Exemple
tags:
- name: users
description:Gestion des utilisateurs
- name: products
description:Gestion des produits
chemins:
/users:
get:
tags:
- users
/products:
get:
tags:
- products
- name: users
description:Gestion des utilisateurs
- name: products
description:Gestion des produits
chemins:
/users:
get:
tags:
- users
/products:
get:
tags:
- products
Champs d'extension
Viax-Ajoutez des propriétés personnalisées avec un préfixe :
Exemple
lpaths:
/users:
get:
x-controller: UserController
x-rate-limit: 100
x-deprecated: false
/users:
get:
x-controller: UserController
x-rate-limit: 100
x-deprecated: false
Ces fonctionnalités avancées peuvent vous aider à créer une documentation API plus structurée, maintenable et professionnelle.
Autres extensions