I need to create a UML class diagram and a use case diagram for a RESTFul API that I developed using API Platform and Symfony 3.2 (backend) and Ionic 2 (frontend).
But i dont exactly know how to describe the structure of my backend API through the class diagram.
If anyone has any idea or could be of any help, i'd truly appreciate it. Thank you!
So the solution to my problem was a bit of all of the following :
https://www.ibm.com/developerworks/rational/library/design-implement-restful-web-services/ :
I concluded from this that, although it's difficult to model a restful api in a class diagram (since it's basically just a bunch of methods), consider the classes like "Resources", add the methods (basically the HTTP methods), and the paths to each resource.
This was also of huge help:
https://firstinfinity.wordpress.com/modeling_rest_web_services/
Another (simpler) way was to use tools like Pikturr, which transform your Swagger into a UML diagram.
Softwares for designing REST APIs :
Visual Paradigm
IBM Rational Software Architect
I hope this helps.
Api Platform automatically generates a Swagger documentation for your API at the URL http://localhost/docs.json.
You can generate an UML diagram from the Swagger documentation using tools like https://github.com/nrekretep/pikturr
It is too late, but this is another approach.
If you do not know about Visual Paradigm you can give it a try.
You can use this content, Visual Paradigm - How to Design REST API with UML?. It is easy, to represent your REST API. I prefer Postman Collections BTW (it is not UML).
But if you are doing some other kinds UML artifacts for documentation purposes. Well, Visual Paradigm gives you a bunch of UML diagrams to do that. So you keep that ecosystem of diagrams.
See ya.
The real answer for the question is to use an UML Component Diagram, since its very purpose is to model architectures based on services. Check this link for more info: https://diagramasuml.com/componentes/
Related
I have several services, each one exposed through REST API with ASP.NET Core Web API. I use Swashbuckle for ASP.NET Core tooling in order to automatically generate from my controllers and DTOs all the necessary documentation and visualize it in SwaggerUI. I found this tooling really great, with little annotations on my models and my controllers already provides many features out of the box, such as a UI client to try out the REST API endpoints.
But with this solution each service has its own dedicated SwaggerUI instance and therefore UI.
I would like to offer to my customers a wiki-like documentation with a navigation menu, where, for instance, they can browse sections regarding all the endpoints exposed by my services and have on each page the same features offered by SwaggerUI.
It can be achieved by creating my own web application but I was wondering whether an out of the box solution or some tool that might ease such integration already exists.
I tried Slate but I felt like I had to re-invent the wheel in order to automate at least the creation of the basic API documentation, namely controller definition, response definition and descriptions. Does anyone have any suggestion?
I faced this very issue recently working in a microservices architecture, you're absolutely right. There is not need to reinvent the wheel.
I really can't recommend redoc by Redocly enough in this case.
Have a look at the multiple-apis example.
I have read the swagger definitions and the format and understood that swagger definition is used to describe the APIs.
Would it be better to write the swagger definition and then the API? or to write the API first and then the swagger? I have no experience with this and I would like to write a REST API and a swagger file for an application.
I don't think the order really matters. Both methods are given legitimacy in the Swagger Getting Started Guide. The key thing is that one should be generated from the other, so you don't have to manually maintain both.
In the comments, cricket_007 has already mentioned that tools exist to generate the web service skeleton from the swagger definition. Using these tools, it would make sense to write the swagger definition first. This is the Top Down approach from the getting started guide.
From the Swagger getting started guide linked above, you can see that there are also tools available to generate Swagger docs from java code, provided you are using a particular framework like JAX-RS. This is the Bottom Up approach.
It comes down to personal preference. If you are the kind of person that would rather not "couple" your code base to Swagger and make sure that your application does not depend on Swagger to work, then the bottom up approach is best. However, if you want to fully embrace the Swagger tool chain and really "buy in" to it, then the top down approach is probably the best.
Also, if this is for educational purposes, then think about what you want to learn about. If you want to learn about writing JSON REST APIs from scratch (or using something like JAX-RS), then the bottom up approach will teach you more. However, if your goal is to learn as much as possible about Swagger, then the top down approach will be better.
I like the TDD approach to documenting your restful api with spring-rest-docs. However, I love "API Playground" feature enabled by swagger specification. I wish there was a way to get best of both worlds.
Is there a way to build swagger2 specs from spring rest docs? may be via building custom request/response preprocessors.
Do you have any thoughts or recommendations?
There's not out-of-the-box support for this in Spring REST Docs at the moment. The issue that you opened will track the possibility of adding such functionality. In the meantime, your best bet would be to look at writing a custom Snippet implementation that generates (part of) a Swagger specification.
Typically, a Spring REST Docs snippet deals with documentating a single resource, whereas a Swagger specification describes an entire service. This means that the Swagger specification Snippet implementation will need to accumulate state somehow, before producing a complete specification at the end. There are lots of ways to do that (in memory, multiple files that are combined in a post-processing step, etc.). It's not clear to me that one approach is obviously the right one so some experimentation would be useful. If you do some experimentation, please comment on the issue that you opened with your findings.
Spring REST Docs was released recently and the documentation says:
This approach frees you from the limitations imposed by tools like Swagger
So, I wanted to ask when Spring REST Docs is preferable to use comparing to Swagger and which limitations it frees.
I just saw a presentation here that touches on your question among other topics:
https://www.youtube.com/watch?v=k5ncCJBarRI&t=26m58s
Swagger doesn't support hypermedia at all / it's URI centric
Swagger's method of inspecting your code can lag behind your code. It's possible make a change in your code that Swagger fails to understand and won't process properly until Swagger gets updated.
Swagger requires lot of annotation, and it's painful to include the descriptive text you want in an api document in annotations.
There are just some things that Swagger can't figure out from inspecting your code.
In any case, these are just a couple of points. The presenter does a much better job discussing it than I could.
I thought I would chime in to give a little bit more context surrounding Swagger, what it is, and what it is not. I believe this might help answer your question.
Swagger 2.0 is being adopted by a lot of big names and big platforms like Microsoft Azure, Paypal, SwaggerHub.com, DynamicApis.com, etc... Something to keep in mind is that Swagger is very simply a specification. It is not a framework. There are a lot of frameworks out there built to generate Swagger output that crawl through your code looking at your API information in order to build the Swagger 2.0 JSON file that represents your API. The Swagger UI that you see your APIs on is driven directly from this Swagger 2.0 JSON file. fiddler it to check it out
It is important to note that a framework that was created to allow you to "use swagger" is not how Swagger has to work (i.e. it is completely up to the implementation of the 3rd party framework). If the framework you are using to generate your Swagger 2.0 documents and UI is not working for you then you should be able to go find another framework that generates the Swagger artifacts and swap the technologies out.
Hope this helps.
From Spring REST docs:
The aim of Spring REST Docs is to help you to produce documentation for your RESTful services that is accurate and readable
This test-driven approach helps to guarantee the accuracy of your service’s documentation. If a snippet is incorrect the test that produces it will fail.
Spring REST docs advantages:
Documentation is written in the test code so it does not overload main code with lots of annotations and descriptions
Generated docs and examples are accurate because related test must pass
Docs can provide more specific and descriptive snippets
Format is suitable for publishing
Spring REST docs disadvantages:
Requires more work
Documentation provides request/response examples but don't provide interactive tools to modify and try out requests
Swagger advantages:
Quick, automated generation from a code
Interactive request execution - can be used for acceptance testing
Built around the OpenAPI Specification
Swagger disadvantages:
For more descriptive documentation it will require a lot of annotations
Tests are not related to the documentation so sometimes documention may deviate from reality
There is some limitation with swagger and the specific spring stack.
For example : with "param" in your Request Mapping you can define more than one method with the same url ans so simplify your code.
But swagger show you just one method
One disadvantage with Swagger is: it cannot handle models which have cyclical dependencies. If a model has cyclical dependency and if swagger is enabled, then spring boot server crashes.
Striving to ship a well documented application, I'm looking for a good way to describe a REST API for my Grails Application users.
I know that REST calls should be simple enough to be described by examples, but it doesn't feel formal enough.
I've spent a couple of hours looking for a solution suggested by other Grails users, but didn't find a neat solution besides a recommendation to use WADL or WSDL 2.0
This looks like a good direction, but there must be a simple way to do it in Grails.
I'd appreciate some guidance for a process to generate a REST API based on my model objects preferably with the ability to filter or control the exposed fields, plus, a nice graphical way to present it (something like the XSD Eclipse plugin)
Thanks!
Guy
I would suggest to avoid WADL or WSDL for API documentation, you can see this question where I explained my reasons: Why the slow WADL uptake.
WADL or WSDL are usually used for automatic client code generation, they are not human readable documentation. I don't think WADL or WSDL are very useful for a user to figure out how to consume the resources correctly.
I prefer the good old html documentation, for example I like the way twitter documented their API
If you insist on automatic generation of resources documentation I can recommend on the ATOM service document. Many REST framework can generate it automatically based on the resources annotations. (e.g. Apache Wink)