I have to integrate spring rest docs in a legacy project were they use a bunch of custom annotation (such as for example the user roles).
Is there a way in spring rest docs to document this annotation?
Spring REST Docs works at the level of HTTP requests and responses. By design, it doesn't know anything about annotations or how those requests are handled and the responses created. This ensures that what you're documenting is at the same level as a client interacting with your service over HTTP.
If you want to include information about #PreAuthorize or an annotation that is similar to it, you will have to write something yourself to do that. If you want to fit into the REST Docs way of doing things, you could implement a custom Snippet that's configured with a class or method from which it extracts the annotation using reflection and generates some documentation from it.
Related
Why would one like to integrate JAX-RS(Jersey) using Rest API to Struts2? Struts2 is itself a mvc framework, so why would anyone want to integrate these both? If combined, how will the resulting framework be(I wanted to know if REST API just control the controller part of MVC).
There is a RESTful plugin called struts2-rest-plugin that has been included with the framework since version 2.1.1. A fair amount of information on the plugin can be found here.
Essentially, the plugin uses a custom action mapper that examines the request and based upon the HTTP Method used in conjunction with the URI, it dispatches the request to one of several different method names (e.g. GET /movies dispatched to index() method of action).
Just because Struts2 is an action-based framework does not mean a RESTful solution cannot be included as an alternative for developers. Spring MVC offers similar solutions themselves and it is also an action-based framework.
If you consider your JSON response as your view, you'll see that the fact that Struts2 is based on MVC design makes logical sense. Your model is simply the data structure you are returning to the client and your controller is the action.
Consider reading the link above on the plugin and you'll get a better picture of how the two can be integrated. If you want to return JSON but don't necessarily want to offer RESTful URLs in your Struts2 application, you can also consider the JSON plugin, found here.
I am not sure about Struts2, but in the past Struts1 did not have a "Rest" adapter built in. Jersey provides the cool #annotations that will easily serialize your datamodel and will push you in a "Restful" direction. Jersey does not provide an MVC framework as much as it provides convenience methods to work in a Restful/resource based way.
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.
I have a very simple service project (SpringBootApplication) that exposes a REST endpoint via a Spring Boot controller class. The controller maps an /events endpoint that converts a simple incoming event DTO into a slightly different event entity object that is then persisted in a database via a org.springframework.data.repository.CrudRepository instance.
In my controller, I am only mapping the POST operator because I don't want my clients to be able to GET, PUT or DELETE data from the service.
During a security scan today, I discovered that the service is exposing a /eventsEntities endpoint, which appears to be mapping all of the CrudRepository verbs into the REST endpoint.
Any idea how I managed to enable this automatic endpoint and more importantly, how to disable it? I'm using Spring Boot 1.2.2.
After some additional digging, I realized that I had inadvertently included org.springframework.boot:spring-boot-starter-data-rest in my compile dependencies. That starter includes spring-data-rest-webmvc, which exposes JPA data over REST. Removing that dependency resolved the issue.
Hope my realization helps someone else in the future.
I want to host restful webservice from CQ5. Basically the intention is to expose all the users present in CQ5 to external systems based on some parameters like modified date, user state etc.
I went through https://chanchal.wordpress.com/2015/01/11/using-jax-rs-and-jersey-to-write-restful-services-in-osgi-apache-felix-adobe-cq5aem/ as I could find only this post online, but as I am a beginner I couldn't implement it. Need guidance in implementing such RESTful webservice in CQ5
CQ5 is based on Apache Sling which is inherently RESTful, so you don't usually need additional libraries. In your case (and unless the users info is already available as Sling resources, I don't remember if that's the case) implementing a Sling ResourceProvider is enough to provide a browseable RESTful representation of those resources. See the Sling docs for more info, they point to a simple PlanetResourceProvider as a minimal example.
Couldn't get the REST webservices working with AEM/CQ5. Even after installing the packages for JAXB for CQ5. It seems like sling overrides the resolving before it goes to the JAXB annotation handler. Due to lack to time had to implement an alternative approach where CQ5 will be timely writing the json data to an shared location as json file and the third party applications will fetch the files from there.
This will however impact the performace as schedulers are to be written and also it's not a recommended approach but still it will work in my scenario.
Thanks all for helping me.
As far as I understood, unlike Rails, Yii2 still doesn't use RESTful routing for CRUDs.
What could be the most efficient way to generate new CRUD with gii and add REST routing support to it?
I've done some background search and found the following:
a lot of information about how to easily build REST API application - http://www.yiiframework.com/doc-2.0/guide-rest-quick-start.html (which is not a thing I really need - it's only useful for backend applications)
an article by qiangxue https://github.com/yiisoft/yii2/blob/master/docs/guide/rest-routing.md on how to enable REST routing for CRUDs
a gist added by cebe (https://gist.github.com/cebe/5674918) doing almost the same thing like qiangxue proposed in other way
So it's all about configuring UrlManager and implemetation of backend API applications.
Unfortunately, I also need to somehow add a REST routing support to CRUD controller generated by default (with its verb-based filters and a base class that is not specialized for REST, unlike yii\rest\ActiveController for example). At the same time a generated by default GridView widget code doesn't support REST routes, but only utilizes GET+POST verbs.
Really appreciate certain list of things to do :)