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?

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

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

Comments

[Geert Bellekens]

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

[Chris Aelbrecht]

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

[www.admiraalit.nl]

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

[Darrell Teague]

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

[Will I Am]

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

[Muka]

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?