Générer de la documentation HTML à partir de WSDL [fermé]
quelles sont vos approches pour générer une sorte de documentation lisible par l'humain à partir des WSDLs? Dans le passé, j'ai utilisé WSDL viewer<!-(Par Tomi Vanek) (voir mon billet de blog sur l'intégration dans NAnt) et je suis content des résultats, mais je suis intéressé par toutes les alternatives possibles.
j'ai aussi entendu parler de x3sp, mais je n'ai pas essayé.
10 réponses
j'ai essayé plusieurs alternatives
- TechWriter for Web Services: très puissant, mais la sortie HTML a été (voir les commentaires) multi-fichier. En outre, les commentaires indiquent qu'il est retiré, mais ce n'est plus le cas.
XML Editor: il ne traite pas le schéma intégré. - Altova XML Spy: Il n'a pas de processus types anonymes.
et a fini par Modifier WSDL viewer à mon besoin.
utiliser http://code.google.com/p/wsdl-viewer/ et xsltproc de cygwin
xsltproc wsdl-viewer.xsl downloaded-wsdl.xml > documetnation.html
Fonctionne comme un charme
maintenant, il y a un outil de plus pour cela, appelé "DocFlex / XML WSDLDoc".
il s'agit d'un nouveau générateur de documentation WSDL/XSD qui vous permettra de documenter tout nombre de fichiers WSDL et XML schema (XSD) ainsi que toute interconnexion entre eux.
il y a aussi une option pour l'inclusion automatique des diagrammes XSD générés par Altova XMLSpy ou Oxygen XML. En effet, n'importe lequel d'entre eux peut être utilisé comme diagrammation dynamiquement liée moteur.
CARACTÉRISTIQUES PRINCIPALES
- Génération d'une seule encadrée (Javadoc) documentation HTML par des fichiers WSDL/XSD ensemble. (Si vous avez trop de fichiers d'entrée, vous pouvez les choisir tous en utilisant un pathname de type Ant).
- traitement D'un nombre quelconque de schémas XML (avec WSDL) y compris:
- sous la forme de fichiers XSD séparés
- XML schéma intégré dans WSDL (
<wsdl:definitons>/<wsdl:types>d'un élément
- traitement de tout référencés fichiers WSDL et schémas XML, en particulier:
- traitement Correct de tous
<wsdl:import>,<xs:import>,<xs:include>,<xs:redefine>éléments trouvés dans tous les fichiers WSDL/XSD concernés. - chargement et traitement automatiques (c.-à-d. inclusion dans la portée de la documentation) tous directement / indirectement référencés WSDL / XSD fichier.
- traitement Correct de tous
- Sophistiqué documentation de XSD composants (documentation du schéma XML):
- prise en charge de tout schéma de conception XML.
- possibilité d'inclusion automatique de diagrammes de XSD générés par XMLSpy ou oxygène XML, avec le support de tous les hyperliens de diagramme.
- Documentation de tous les interconnexions entre les définitions WSDL et les composants XSD:
- hyperliens à partir des messages WSDL vers les détails des éléments/types xsd décrivant les données du message.
- dans XSD element / type details, la liste de toutes les définitions WSDL où elles sont utilisées.
- copier les annotations des éléments/types XSD dans la documentation des messages WSDL (et même des opérations) où ils sont utilisés.
- Possibilité illimitée personnalisation. WSDLDoc est en fait un template défini pour DocFlex / XML, un système logiciel pour le développement et l'exécution de la documentation haute performance et des générateurs de rapports à partir de toutes les données stockées dans des fichiers XML.
exemple
Voici une démonstration de cette documentation (elle a été générée par une seule source fichier: http://developer.ebay.com/webservices/latest/ebaySvc.wsdl):
le HTML lui-même: http://www.filigris.com/docflex-xml/wsdldoc/examples/html/ebaySvc/index.html
liens
Altova's XMLSpy génère de la documentation HTML à partir D'une WSDL ... mais ce n'est pas gratuit ;)
je viens de découvrir que Notepad++ avec le plugin D'outils Xml installé peut aussi effectuer des transformations xsl. Si vous lui fournissez le WSDL-viewer.xsl mentionné plus tôt et le fichier wsdl, vous obtiendrez un html joliment formaté en conséquence.
je sais que c'est la méthode de documentation d'un pauvre homme, mais j'ai utilisé ouvrir le XSD de la wsdl dans visual studio et faire des impressions snag-it avec des commentaires et des flèches ajoutées pour plus de clarté et notre client semble l'avoir aimé sans avoir à utiliser un autre outil. Vous ne l'avez peut-être pas, mais vous pouvez utiliser une version à partir d'un abonnement VPC ou MSDN gratuit.J'ai également utilisé L'éditeur de schéma BizTalk pour visualiser le XSD et le documenter à partir de là en utilisant snag-it ou une autre application de capture d'écran. Je vais l'essayer et utilisez ce que vous avez!
- Bryan
Vous pouvez utiliser "wsimport", qui fait partie du JDK et exécuter Javadoc sur les fichiers générés. En présumant que vous avez mis dans les annotations il les mettra dans la documentation.
un autre outil serait Rational Application Developer qui vous permet de cliquer avec le bouton droit de la souris et générer la documentation HTML avec de jolies images hyperliées.
vous pouvez utiliser iDocIt! pour documenter un WSDL et exporter ensuite la documentation vers HTML. Il s'agit d'un plugin Open source Eclipse téléchargeable ici.
il offre une nouvelle approche de création de documentations avec des grilles thématiques et des rôles thématiques, mais vous n'avez pas besoin de les utiliser. Vous pouvez créer des documentations en texte simple.