Stoplight Avantages et Inconvénients

J'aime le mode d'édition Markdown. Il vous permet d'écrire votre documentation rapidement, tant que vous connaissez Markdown (ce qui est un bon investissement). Ce n'est pas un système WYSIWYG, mais vous serez guidé avec plusieurs champs de formulaire.

Un autre avantage est que vos documents ne sont pas enregistrés dans l'application, mais dans l'un de vos dépôts sous forme de fichiers yaml standard. C'est très puissant et présente deux avantages : vous êtes libre d'emporter votre document partout plus tard (pas de verrouillage) et vous pouvez automatiser la génération de code (par exemple, vous pouvez extraire des informations d'autres sources, les intégrer dans les documents et ensuite les remettre dans Stoplight). Avis collecté par et hébergé sur G2.com.

Pas beaucoup de problèmes jusqu'à présent. Peut-être qu'il a les mêmes problèmes que l'on peut trouver dans des outils similaires : on peut être submergé par les options pour chaque champ ou chaque entrée. Mais c'est normal, car il faut trouver l'équilibre entre l'utilisabilité et les fonctionnalités, surtout lorsqu'il faut suivre une spécification qui ne dépend pas de vous. De plus, j'ai manqué d'une manière de documenter les webhooks de la même manière que je peux documenter l'API, mais encore une fois, c'est probablement plus une limitation d'OpenAPI que de Stoplight lui-même. Avis collecté par et hébergé sur G2.com.

Comme tout le monde, j'ai commencé avec les outils Swagger. Mais c'était écrire trop de code en YAML. Le maintenir était un gros casse-tête. C'était un grand projet. Je devais documenter au moins 100 points de terminaison d'API. Je pensais que le projet prendrait au moins quelques mois, mais j'ai pu le faire en moitié moins de temps. J'ai économisé beaucoup de temps et facturé beaucoup moins au client grâce à Stoplight. La première chose qui m'a impressionné est la rapidité avec laquelle Stoplight Desktop a permis de documenter l'API en OAS. La plupart du temps, je n'avais pas à écrire une seule ligne de YAML ou JSON. Le code côte à côte et l'aperçu étaient un véritable sauveur. L'interface utilisateur de l'outil de bureau était extraordinaire et rend la documentation des API accessible à tout le monde, pas seulement aux développeurs. La création de documents de support d'API était simple grâce au support complet du markdown. Avis collecté par et hébergé sur G2.com.

Eh bien, Stoplight est un peu lent à absorber les changements poussés vers OAS3. Il y a quelques fonctionnalités indisponibles sur Stoplight malgré le fait qu'elles fassent partie de l'oas 3 depuis longtemps. Je ne me souviens pas de celles-ci. Avis collecté par et hébergé sur G2.com.

J'aime la possibilité de remplir rapidement les champs de formulaire plutôt que de devoir taper la structure yaml/json à la main. C'est également très agréable d'avoir Spectral intégré directement dans l'outil, car cela nous aide à automatiser une partie du processus de révision de conception en réduisant le besoin de revoir manuellement les normes de codage autour de la conception des API. Avis collecté par et hébergé sur G2.com.

Lorsque de nouvelles fonctionnalités sont publiées, elles ne semblent pas être testées de manière approfondie et causent des problèmes à l'occasion. Il semble également y avoir une priorité accordée à "sortir de nouvelles fonctionnalités" plutôt qu'à "améliorer celles qui existent". La mise en œuvre de Spectral est agréable, mais il est difficile de maintenir un ensemble de règles cohérent pour des centaines de projets. Avis collecté par et hébergé sur G2.com.

C'est vraiment intuitif et même pour une personne non technique comme moi, c'était facile à comprendre et à rédiger une documentation. Avis collecté par et hébergé sur G2.com.

Markdown est vraiment limité et limite la possibilité de créer une documentation plus créative. Avis collecté par et hébergé sur G2.com.

Pouvoir basculer entre l'interface utilisateur/YAML. Avis collecté par et hébergé sur G2.com.

Les modules peuvent sembler un peu fragmentés. Avis collecté par et hébergé sur G2.com.

Lots of functionality that is available within stoplight, easy to use and merge changes! Avis collecté par et hébergé sur G2.com.

Typically they take long to respond to issues that we face. Avis collecté par et hébergé sur G2.com.

Stoplight est un outil de documentation très convivial pour générer des documents et pour que les développeurs puissent consulter la documentation technique de l'API.

Je suis également fan de leurs autorisations utilisateur granulaires qui nous permettent de gérer les autorisations concernant les pages que les gens peuvent voir. Avis collecté par et hébergé sur G2.com.

Bien que ce ne soit pas une limitation dans la manière traditionnelle de documenter les API, j'aimerais plus de flexibilité de conception pour créer des pages de persona d'entreprise. Avis collecté par et hébergé sur G2.com.

J'aime que Stoplight utilise le format openAPI pour définir les API. J'ai pu intégrer les fichiers de configuration dans d'autres services pour faciliter les tests d'API également. Avis collecté par et hébergé sur G2.com.

Je n'aime pas que GitHub soit nécessaire pour collaborer et partager votre travail. Je préférerais une méthode de collaboration qui enregistre automatiquement mes modifications et donne à mon équipe l'accès pour éditer. De plus, j'utilise Azure DevOps au quotidien, mais j'ai créé un compte GitHub pour la collaboration sur Stoplight parce que c'était gratuit. Cela m'a sorti de notre écosystème existant. Avis collecté par et hébergé sur G2.com.

L'interface utilisateur et la connexion à Github et autres dépôts. La structure des dossiers et du projet et l'écran pour éditer et ajouter des informations sont assez simples et faciles à utiliser. Avis collecté par et hébergé sur G2.com.

Personnellement, je pense que la possibilité de documentation d'API pilotée par des événements ou asynchrone est insuffisante. Avis collecté par et hébergé sur G2.com.

L'interface utilisateur est conviviale. La disponibilité de serveurs mock automatiques facilite le processus de test du design. Facile à collaborer avec les workflows Git. Avis collecté par et hébergé sur G2.com.

La seule chose que je n'aime pas est l'incapacité d'afficher la réponse du service Web lorsque le temps de réponse dépasse 10000 ms. Avis collecté par et hébergé sur G2.com.