12

My customer wants me to create a specification for a future REST API by using Enterprise Architect (SparxSystems). The deliverable should be well formatted text (can be html, docx or rtf). A class diagram should give a picture of the message body.

The only thing I found so far was https://github.com/bayeslife/api-add-in , a plugin for EA to generate RAML and more. Does anybody have a better approach?

www.admiraalit.nl
  • 5,768
  • 1
  • 17
  • 32
  • You should contact Sander Hoogendoorn. He has an approach for modelling microservices, including their REST api in Enterprise Architect. – Geert Bellekens Jun 29 '16 at 11:20
  • Usually (well, always) I go the API way to create documentation. So the above seems to be the best approach unless you want to do everything yourself. – qwerty_so Jun 29 '16 at 11:50
  • @ThomasKilian, What do you mean by "the API way" ? – www.admiraalit.nl Jun 30 '16 at 14:42
  • Simply that I knit my own scarf to get me warm. The API gives me access to anything in a repo. And then I use whatever tool to make a documentation. Personally I used LaTeX since that yields the nicest output. But markdown is a nice alternative too. Unfortunately most people insist on Word documents (so you have two models in the repo and manipulated Word source - argh). – qwerty_so Jun 30 '16 at 18:31
  • Maybe you should explain what you mean by "formatted output of Swagger". – qwerty_so Jul 01 '16 at 20:54
  • @ThomasKilian: I have removed the reference to Swagger and I have added the requirement that a class diagram should be included. – www.admiraalit.nl Jul 03 '16 at 20:04
  • So why not use the doc-gen of EA? – qwerty_so Jul 03 '16 at 20:37
  • @ThomasKilian: Sure, that can be one aspect of the solution. Because REST and EA are both widely used, I thought maybe someone has a template or a plugin or a detailed description of how to do it. – www.admiraalit.nl Jul 06 '16 at 06:42
  • @GeertBellekens: Sander H. doesn't respond. Did he present his ideas on one of the EAUG conferences? If you have a conference date, I can download his presentation from the EAUG site. – www.admiraalit.nl Jul 06 '16 at 06:44
  • 1
    Strange, maybe he's on holidays. But yes, he did at the Brussels EAUG in 2015. See http://eausergroup.com/past-events/september-2015-brussels/brussels-presentations-for-download-2015?download=106:modelling-microservices-in-ea-sander-hoogendoorn – Geert Bellekens Jul 06 '16 at 06:48
  • @GeertBellekens, Thanks, this is really useful. Only a few slides show his approach with regarding to the use of EA, but there are very interesting. – www.admiraalit.nl Jul 13 '16 at 08:17
  • I like this quesiton- however, I am puzzled as it seems a bit off. I can see that one might want to create a data model specification in EA. The problem with this is that EA's documentation is extremely clunky. Is there a process that one can follow to get documentation in a user-friendly format (e.g. like Swagger produces)? – theMayer Jul 13 '16 at 16:15
  • @theMayer Try looking into eaDocX. As said, I'm happy with creating documentation through the API. – qwerty_so Jul 13 '16 at 18:42
  • 1
    https://sparxsystems.us/home/software/integration-solutions/restapi/ – Chris Aelbrecht Mar 18 '19 at 07:17

3 Answers3

8

The presentation 'Modeling Microservices' by Sander Hoogendoorn contains some interesting slides about modeling a REST API in Enterprise Architect. The presentation is available on slideshare.net. The most interesting slide is slide #75. Here is the picture shown on that slide:

Class model of REST service

(Class and attribute names are in Dutch. Verklaring means Declaration and Verklaringen means Declarations. But the business behind this example is not relevant.)

It would be nice if someone would have a plugin for Enterprise Architect to convert these class diagrams into Swagger specs (Open API specs).

www.admiraalit.nl
  • 5,768
  • 1
  • 17
  • 32
4

Update 2019/03/18

Use this plugin and guideline: https://sparxsystems.us/go/restapi/

Original answer

I'm using Enterprise Architect at this moment to model an API. For this projects you have users that are granted a budget to buy certain products. The model is not yet complete, but I'm adding it here as reference.

In EA I added some additional stereotypes: Path, Resource and Representation + a new datatype ParamQuery.

To model the API you create a new class diagram and start by the root of your API as a class of stereotype "Application". Next you add your Resources and Paths. For each Resource you add the necessary GET, POST, PUT etc. operations. If QueryParams are passed along in the string for the GET operations you add them as Parameters for the operation, but as type QueryParam (you need to create it the first time). For the messagebody of POST operations you add a parameter of the class type it represents.

Next you add the "representation" classes, used by the Resources.

enter image description here

Boundless
  • 2,444
  • 2
  • 25
  • 40
Chris Aelbrecht
  • 2,051
  • 21
  • 25
  • 4
    Provided URL (no longer) resolves. Updated URL: https://sparxsystems.us/go/restapi/ ... however, note that what developers would consider an API contract (OpenAPI, JSON Schema et al) is not really supported (no forward/reverse engineering from YAML or JSON for example). – Darrell Teague Feb 27 '20 at 20:47
  • Seems like the new URL ends in a 404 after you fill and submit the marketing form. – Will I Am Mar 12 '20 at 15:52
  • Swagger provides an excelent APIs documentation. I would like to link a use case (or user interface) element designed on Enterprise Architect with a respective endpoint on Swagger. Would be possible? – Muka Dec 05 '21 at 20:59
0

I recommend you to use postmanerator service which generate documentation for API automatically just save the API Calls in postman in a collection and pass this collector to this service it generates the documentation for you postmanerator link: postmanerator

I hope my answer would be useful

Alaa M. Tekleh
  • 6,938
  • 4
  • 16
  • 29