La spécification OpenAPI (OAS) offre un moyen puissant et standardisé de décrire les API. L'une des fonctionnalités les plus précieuses de la spécification est lacomponents objet, qui permet la réutilisation de divers éléments dans une API, garantissant la cohérence et réduisant la redondance.

Comprendre les composants de l'OAS

Lecomponents L'objet peut contenir des schémas, des paramètres, des réponses, des en-têtes, des corps de requête, des schémas de sécurité et des exemples. Ce conteneur centralisé améliore la réutilisabilité et la maintenabilité de vos définitions d'API.

Composants couramment réutilisés

Schémas

Les schémas définissent la structure des corps de requête et de réponse. Ils peuvent représenter un objet utilisateur, une structure de message d'erreur ou toute autre entité de données.

Exemple:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

Paramètres

Les paramètres sont réutilisables dans plusieurs opérations, telles que l'identifiant dans les chemins ou la limite et le décalage pour la pagination.

Exemple:

components:
  parameters:
    userId:
      name: userId
      in: path
      required: true
      schema:
        type: integer
    limitParam:
      name: limit
      in: query
      schema:
        type: integer
        default: 10

Réponses

Les structures de réponse communes, notamment pour la gestion des erreurs, peuvent être définies une seule fois et réutilisées, garantissant ainsi un comportement cohérent de l'API. Exemple:

components:
  responses:
    NotFound:
      description: The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

En-têtes

Les en-têtes standard pouvant être utilisés sur différents points de terminaison peuvent être définis une fois et réutilisés.

Exemple:

components:
  headers:
    X-Rate-Limit:
      description: The number of allowed requests in the current period
      schema:
        type: integer

Schémas de sécurité

La définition de schémas de sécurité communs vous permet de les réutiliser dans l'ensemble de l'API, garantissant ainsi des pratiques de sécurité cohérentes.

Exemple:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

Meilleures pratiques pour la réutilisabilité

Conventions de nommage

Utilisez des noms clairs et descriptifs pour les composants, afin que les développeurs puissent les comprendre et les réutiliser plus facilement. Par exemple, User pour un schéma d'objet utilisateur, NotFound pour une réponse d'erreur 404 courante.

Organisation et structure

Organisez vos composants de manière logique, en les classant peut-être par leur type (par exemple, réponses, paramètres) ou par leur domaine (par exemple, authentification, utilisateurs, produits).

Éviter la sur-modularisation

Bien que la réutilisabilité soit essentielle, trop de granularité peut compliquer la compréhension et la maintenance des spécifications de l'API. L’équilibre est crucial.

Exemples de scénarios

Schéma commun de réponse aux erreurs

components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string

Réutilisation des paramètres de requête pour la pagination

paths:
  /users:
    get:
      parameters:
        - $ref: '#/components/parameters/limitParam'
        - name: offset
          in: query
          schema:
            type: integer
            default: 0

En-tête d’autorisation partagée

paths:
  /protected/resource:
    get:
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Success

Conclusion

Utiliser efficacement lecomponents Un objet dans OAS peut grandement améliorer la cohérence et la maintenabilité de vos spécifications API. En adhérant aux meilleures pratiques et en tirant parti de l'éditeur d'API intuitif d'APIGIT, les développeurs peuvent créer des définitions d'API efficaces, réutilisables et bien organisées.