Create spec for REST API in Enterprise Architect

Question

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?

Puissance

You should contact Sander Hoogendoorn. He has an approach for modelling microservices, including their REST api in Enterprise Architect. – Dampproof

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. – Supremacist

@ThomasKilian, What do you mean by "the API way" ? – Puissance

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). – Supremacist

Maybe you should explain what you mean by "formatted output of Swagger". – Supremacist

@ThomasKilian: I have removed the reference to Swagger and I have added the requirement that a class diagram should be included. – Puissance

So why not use the doc-gen of EA? – Supremacist

@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. – Puissance

@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. – Puissance

Strange, maybe he's on holidays. But yes, he did at the Brussels EAUG in 2015. See eausergroup.com/past-events/september-2015-brussels/… – Dampproof

@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. – Puissance

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)? – Vallombrosa

@Vallombrosa Try looking into eaDocX. As said, I'm happy with creating documentation through the API. – Supremacist

sparxsystems.us/home/software/integration-solutions/restapi – Arjun

Answer 1

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.

Arjun

Provided URL (no longer) resolves. Updated URL: 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). – Pulsimeter

Seems like the new URL ends in a 404 after you fill and submit the marketing form. – Verdict

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? – Merriemerrielle

Answer 2

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 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).

Puissance

Answer 3

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

Hoyt

Thanks, but postmanerator is not a solution for using the tool Enterprise Architect. – Puissance