```html
En tant que développeur travaillant avec des API, vous connaissez probablement Postman, un outil populaire pour tester et documenter vos points de terminaison. Cependant, lorsqu'il s'agit de partager votre documentation API dans un format standardisé comme OpenAPI 3.0, vous pourriez vous sentir perdu.
N'ayez crainte ! Ce guide complet vous guidera tout au long du processus de conversion de vos collections Postman en spécifications OpenAPI 3.0, en mettant l'accent sur le package npm populaire postman-to-openapi
.
Pourquoi convertir Postman en OpenAPI ?
Avant de commencer, abordons rapidement pourquoi vous pourriez vouloir convertir vos collections Postman en OpenAPI :
- Standardisation : OpenAPI est une norme industrielle pour décrire les API RESTful, garantissant que votre documentation est cohérente et facilement compréhensible par les autres développeurs.
- Interopérabilité : De nombreux outils et plateformes prennent en charge OpenAPI, ce qui facilite l'intégration avec d'autres systèmes et services.
- Documentation : OpenAPI fournit un format clair et lisible par l'homme pour la documentation de l'API, ce qui permet aux autres de comprendre et d'utiliser plus facilement votre API.
- Génération de code : Vous pouvez utiliser les spécifications OpenAPI pour générer des bibliothèques clientes et des stubs de serveur, ce qui simplifie votre processus de développement.
Maintenant, voyons comment réaliser cette conversion !
Utiliser postman-to-openapi
: un guide étape par étape
Le package npm postman-to-openapi
est un outil puissant pour convertir les collections Postman en spécifications OpenAPI 3.0. Voici un guide étape par étape sur la façon de l'utiliser :
Étape 1 : Installer le package postman-to-openai
via npm
Tout d'abord, vous devrez installer le package. Ouvrez votre terminal et exécutez :
npm install postman-to-openapi
Ou si vous préférez yarn :
yarn add postman-to-openapi
Étape 2 : Utiliser postman-to-openai
dans Node.js
Une fois installé, vous pouvez utiliser le package dans votre projet Node.js. Voici un exemple simple :
const postmanToOpenApi = require('postman-to-openapi')
const postmanCollection = './path/to/your/collection.json'
const outputFile = './output/openapi.yml'
async function convertCollection() {
try {
const result = await postmanToOpenApi(postmanCollection, outputFile, {
defaultTag: 'General'
})
console.log(`OpenAPI specs: ${result}`)
} catch (err) {
console.error('Conversion failed:', err)
}
}
convertCollection()
Ce script convertira votre collection Postman en un fichier YAML OpenAPI 3.0.
Étape 3 : Utilisation personnalisée de postman-to-openapi
Le package postman-to-openapi
propose plusieurs options pour personnaliser votre conversion. Voici quelques options utiles :
defaultTag
: Définir une balise par défaut pour toutes les opérations (par défaut : 'default').outputFormat
: Choisir entre 'yaml' ou 'json' (par défaut : 'yaml').includeAuthInfoInExample
: Inclure les informations d'authentification dans les exemples (par défaut : false).
Modifions notre script pour utiliser ces options :
const postmanToOpenApi = require('postman-to-openapi')
const postmanCollection = './path/to/your/collection.json'
const outputFile = './output/openapi.json'
async function convertCollection() {
try {
const result = await postmanToOpenApi(postmanCollection, outputFile, {
defaultTag: 'MyAPI',
outputFormat: 'json',
includeAuthInfoInExample: true
})
console.log(`OpenAPI specs: ${result}`)
} catch (err) {
console.error('Conversion failed:', err)
}
}
convertCollection()
Ce script générera un fichier JSON avec les informations d'authentification incluses dans les exemples et toutes les opérations étiquetées comme 'MyAPI'.
Et si je ne veux pas utiliser le package postman-to-openapi
?
Bien que le package postman-to-openapi
soit idéal pour les conversions simples, vous pourriez parfois avoir besoin de plus de contrôle ou avoir des exigences spécifiques. Explorons quelques techniques avancées.
Option 1. Utiliser APIDog pour la conversion de Postman en OpenAPI
APIDog est un autre excellent outil qui peut vous aider à convertir les collections Postman au format OpenAPI. Voici un guide rapide sur la façon de l'utiliser :
- Connectez-vous à APIDog et accédez au menu "Paramètres".
- Sélectionnez "Importer" parmi les options.
- Choisissez le fichier de collection Postman que vous souhaitez importer. APIDog importera et convertira votre collection, vous permettant d'afficher et de modifier la documentation API résultante.

4. Cliquez sur le bouton Exporter les données et choisissez d'exporter au format OpenAPI 3.0.

Mais attendez, APIDog n'est pas simplement un convertisseur de collections Postman au format OpenAPI. C'est une alternative facile à utiliser qui vous fait oublier de payer pour Postman Enterprise.
APIDog propose des fonctionnalités supplémentaires telles que les tests d'API et les serveurs simulés, ce qui en fait une solution complète pour le développement et la documentation d'API. Voici ce que vous obtenez d'APIDog au lieu de vous abonner à Postman pour 19 $/mois :
- Création d'API illimitée
- Aucune restriction de flux et exécutions illimitées du Collection Runner
- Appels d'API illimités
- Appels de serveur simulé d'API illimités
Ceux-ci sont tous disponibles dans la version gratuite d'APIDog !
De plus, pour seulement 9 $/mois, vous pouvez accéder à toutes les fonctionnalités du plan Postman Profesional qui vous coûterait 39 $/mois !
Option 2. Utiliser l'API Postman pour la conversion
Postman lui-même propose une API qui peut transformer les collections au format OpenAPI. Voici comment vous pouvez l'utiliser :
- Obtenez votre clé API Postman à partir des paramètres de votre compte.
- Utilisez la commande curl suivante (remplacez les espaces réservés par vos valeurs réelles) :
curl --location --request GET 'https://api.getpostman.com/collections/{{collectionId}}/transformations' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{postman-api-key}}'
- La réponse contiendra la spécification OpenAPI. Vous pouvez l'enregistrer dans un fichier pour une utilisation ultérieure.
Option 3. Outils en ligne pour la conversion de Postman en OpenAPI
Si vous préférez une solution rapide et sans code, vous pouvez utiliser des outils en ligne pour une conversion rapide. Voici comment l'utiliser :
- Choisissez parmi l'un des outils en ligne gratuits disponibles.
- Téléchargez votre fichier JSON de collection Postman ou collez l'URL de la collection.
- Cliquez sur "Convertir" et téléchargez la spécification OpenAPI résultante.
Cette méthode est idéale pour les conversions ponctuelles ou lorsque vous ne souhaitez pas configurer un environnement de développement.
Comment convertir Postman en OpenAPI sans tracas : conseils et meilleures pratiques
Même avec les meilleurs outils, vous pourriez rencontrer quelques problèmes. Voici quelques problèmes courants et leurs solutions :
- Fractionnement des collections : divisez les grandes collections en parties plus petites et plus gérables. Cette approche permet une conversion et une maintenance plus faciles des spécifications OpenAPI résultantes.
- Utilisation de dossiers : Organisez votre collection Postman à l'aide de dossiers pour créer une structure logique. Cela vous aidera à générer une spécification OpenAPI bien organisée et à faciliter la navigation.
- API Transformer : Utilisez des outils comme API Transformer, qui peuvent gérer de grandes collections Postman et les convertir efficacement en spécifications OpenAPI.
- Validation OpenAPI : Validez votre spécification OpenAPI après la conversion pour vous assurer qu'elle est correcte et complète. Cette étape est cruciale pour identifier tout problème qui aurait pu survenir au cours du processus de conversion.
Ainsi, pour garantir un processus de conversion en douceur, gardez ces conseils à l'esprit :
- Nettoyez votre collection Postman : Avant la conversion, examinez votre collection pour détecter toute incohérence ou élément inutile.
- Utilisez des noms descriptifs : Assurez-vous que vos points de terminaison, paramètres et réponses ont des noms clairs et descriptifs dans Postman.
- Incluez des exemples : Ajoutez des exemples de réponses dans Postman pour enrichir votre documentation OpenAPI.
- Organisez avec des dossiers : Utilisez des dossiers dans Postman pour regrouper logiquement vos points de terminaison, ce qui se traduira par des balises dans OpenAPI.
- Validez la sortie : Après la conversion, utilisez un validateur OpenAPI pour vous assurer que la spécification résultante est valide.
Conclusion
La conversion des collections Postman en spécifications OpenAPI est une étape cruciale pour la standardisation de la documentation de l'API et pour garantir une intégration transparente avec d'autres systèmes.
En suivant les étapes décrites dans ce guide, vous pouvez convertir efficacement vos collections Postman et profiter des avantages offerts par OpenAPI.
Foire aux questions (FAQ)
Q : Quel est le principal avantage de la conversion des collections Postman en spécifications OpenAPI ?
R : Le principal avantage est la standardisation, qui facilite l'intégration avec d'autres systèmes et outils.
Q : Puis-je utiliser des outils en ligne pour la conversion de Postman en OpenAPI ?
R : Oui, des outils en ligne comme p2o.defcon007.com et APIDog sont disponibles pour convertir les collections Postman en spécifications OpenAPI.
Q : Comment puis-je gérer les grandes collections Postman lors de la conversion ?
R : Les grandes collections peuvent être divisées en parties plus petites, organisées à l'aide de dossiers ou converties à l'aide d'outils comme API Transformer.
Q : Est-il nécessaire de valider la spécification OpenAPI après la conversion ?
R : Oui, la validation de la spécification OpenAPI après la conversion est cruciale pour s'assurer qu'elle est correcte et complète.
```