Portail de développeurs à petit budget
Publié le 9 février 2023 par Andrew Owen (4 minutes)
En 2019, j’ai dû créer un portail pour développeurs sans budget. J’ai rédigé l’expérience et, l’année dernière, je l’ai publiée ici sous la forme d’une série en trois parties. Mes exigences étaient qu’il ait la vue à trois volets, avec des contenus, des points d’extrémité et des exemples de code, que les développeurs puissent y contribuer et qu’il prenne en charge les diagrammes. Ma solution consistait à créer un site statique basé sur Markdown avec des API Swagger rendues par ReDoc et des diagrammes fournis par Mermaid. Je devais être sur la bonne voie, car récemment, Redocly a eu la même idée. Son portail pour les développeurs est actuellement en version bêta. Si vous souhaitez le tester, l’entreprise gère désormais son propre site web sur ce portail. Si vous n’avez pas de budget, vous pouvez toujours procéder comme je l’ai suggéré, mais pour 3600 USD par an (au moment où j’écris ces lignes), il existe une solution plus simple qui inclut l’hébergement.
Avant de poursuivre, je tiens à préciser qu’il ne s’agit pas d’un placement de produit rémunéré. J’ai été surpris d’apprendre à quel point cette pratique est répandue. Appelez-moi naïf. J’ai également fini par travailler pour une entreprise dont j’ai déjà défendu les produits sur ce blog. J’aime ce produit. C’est pourquoi j’ai accepté le poste. Mais si je le mentionne à nouveau, je déclarerai mon intérêt. Je n’ai pas besoin de monétiser ce blog, il ne sera donc jamais soutenu par la publicité, que ce soit directement ou indirectement. C’est juste que j’aime beaucoup l’outil libre ReDoc et je pense que 300 dollars par mois est une demande très raisonnable pour une solution de portail de développement.
Alors, qu’est-ce que vous obtenez pour votre argent?
À l’époque de mon portail de développement sans budget, je demandais toujours l’aide d’un développeur frontal pour améliorer l’aspect et la convivialité. Je n’en ai jamais eu, car ils étaient toujours occupés à d’autres tâches. Selon Glassdoor, le salaire annuel moyen d’un développeur frontal est de 84 250 USD. En ce qui me concerne, tout outil qui permet de produire un contenu accessible et de bonne qualité pour le client et qui coûte moins cher que cela est probablement une bonne affaire.
Swagger, OpenAPI et les sites statiques (pris en charge par les générateurs de sites statiques tels que Hugo) permettent d’écrire la documentation en Markdown. C’est important, car les développeurs détestent généralement écrire quoi que ce soit (en particulier les commentaires de code). Donc, si vous pouvez les amener à écrire, vous voulez leur rendre la tâche aussi facile que possible. Et ceux qui écrivent semblent à l’aise avec Markdown.
Les schémas d’API sont excellents. Mais les documents d’API ne fournissent pas à eux seuls toutes les informations dont un développeur a besoin pour savoir comment utiliser une API. Avant d’accéder à un point de terminaison, je dois peut-être d’abord accéder à d’autres points de terminaison pour configurer certaines données. C’est là que les flux de travail sont vraiment utiles, et c’est pourquoi j’ai ajouté le support de Mermaid à mon portail développeur. Mermaid vous permet de créer des diagrammes à partir de Markdown. Cela signifie que vous n’avez pas besoin de maintenir des fichiers images séparés et que les diagrammes peuvent être édités dans un éditeur de code.
Avec un générateur de site statique, vous devez configurer vos propres modèles de page. Redocly vous propose des modèles pour les tutoriels et les guides, les documents contextuels, les pages d’atterrissage, les exemples, les API multiples et les échantillons de code. Avec ma solution sans budget, vous devez gérer votre propre automatisation pour intégrer les documents de l’API dans le portail. Redocly se connecte directement à votre dépôt Git (sur les principales plateformes Git hébergées). Et le portail est automatiquement reconstruit lorsque le registre de l’API est mis à jour.
Je ne sais pas exactement quel cadre Redocly utilise, mais je suppose qu’il s’agit d’un générateur de site statique standard avec des personnalisations. Outre Markdown, il prend en charge MDX. La configuration se fait en YAML et TypeScript. Les composants React peuvent être intégrés dans le Markdown. Si je devais deviner, je dirais qu’il s’agit soit de Next.js, soit de Gatsby, soit de Docusaurus. Il dispose des fonctions habituelles d’optimisation des moteurs de recherche (SEO) et d’intégration d’outils d’analyse. Si quelqu’un me demandait une recommandation pour mettre en place un portail de développeurs aussi rapidement que possible, tout en étant capable d’évoluer pour répondre à la demande, ce serait celle-ci.