Annonce de la prise en charge, en préversion, de la spécification OpenAPI v3 par le service Gestion des API Azure

Publié le 23 janvier, 2019

Program Manager, Azure API Management

La version 3 de la spécification OpenAPI, dernière version de la norme open source largement utilisée pour décrire les API, est désormais prise en charge, en préversion, par le service Gestion des API Azure. L'implémentation de cette fonctionnalité est basée sur le kit de développement logiciel (SDK) OpenAPI.NET.

Ce billet de blog traite des sujets suivants :

  • Avantages de l'utilisation de la spécification OpenAPI pour vos API
  • Création d'API à partir de documents de spécification OpenAPI dans le service Gestion des API Azure
  • Exportation d'API en tant que documents de spécification OpenAPI
  • Étapes restantes avant la mise à disposition générale

Pourquoi utiliser la spécification OpenAPI pour vos API ?

La spécification OpenAPI est une norme largement utilisée. Le projet OpenAPI Initiative est soutenu par une trentaine d'entreprises, dont Microsoft.

La spécification OpenAPI vous permet d'extraire vos API de leur implémentation. Les définitions d'API ne dépendent pas du langage.

En outre, elles sont faciles à comprendre, tout en étant précises. Vos API sont représentées par des fichiers YAML ou JSON, lisibles aussi bien par des humains que par des machines.

L'adoption à grande échelle de la spécification OpenAPI a donné naissance à un vaste écosystème d'outils. Les fonctionnalités des outils vont de la facilitation du processus collaboratif de conception d'API à la génération automatique de kits de développement logiciel (SDK) clients et à l'implémentation de serveurs dans les langages de programmation courants.

Importation des définitions de la spécification OpenAPI v3 dans le service Gestion des API Azure

Si vos API sont définies dans un fichier de spécification OpenAPI, vous pouvez facilement les importer dans le service Gestion des API Azure. Le portail Azure reconnaîtra automatiquement la bonne version de vos fichiers de spécification OpenAPI. Vous pouvez apprendre à importer vos API via l'interface visuelle en suivant le didacticiel « Importer et publier votre première API ».

Importer des API dans Microsoft Azure

Vous pouvez également importer des API à l'aide de l'appel d'API REST, en définissant le paramètre de charge utile contentFormat sur openapi, openapi+json ou openapi-link.

Lors de l'importation, si le champ servers de la spécification contient plusieurs entrées, le service Gestion des API sélectionnera la première URL HTTPS. En l'absence d'URL HTTPS, la première URL HTTP sera sélectionnée. En l'absence d'URL HTTP, l'URL du service back-end sera vide.

La fonctionnalité d'importation présente quelques restrictions. Par exemple, elle ne prend pas en charge les champs examples et multipart/form-data.

Exportation des définitions de la spécification OpenAPI v3 vers le service Gestion des API Azure

Le service Gestion des API Azure vous permet également d'exporter vos API au format de la spécification OpenAPI v3.

Portail de gestion des API

Les spécifications des API peuvent être téléchargées à partir de votre portail de développeurs au format JSON ou YAML. Le portail des développeurs est un site web généré automatiquement et entièrement personnalisable où les visiteurs peuvent découvrir les API, apprendre à les utiliser, les essayer de manière interactive et finalement s'inscrire pour acquérir les clés API.

Vous pouvez également exporter les spécifications via l'interface visuelle du portail Azure ou via un appel d'API REST, en définissant le paramètre de requête de format sur openapi-link.

Exporter des API

Mise en route et prochaines étapes

Vous pouvez essayer la fonctionnalité actuelle en quelques minutes en important vos API à partir de fichiers de spécification OpenAPI. Avant la mise à disposition générale de cette fonctionnalité, nous implémenterons l'exportation au format JSON via un appel d'API REST. Dans les mois à venir, nous ajouterons également la prise en charge de l'importation et de l'exportation de la spécification OpenAPI v3 dans le kit de développement logiciel (SDK) PowerShell.

Donnez-nous votre avis