I am using an Swagger interface for a REST API app in Quarkus and seems that all my methods/Classes are show on Swagger, so i want to removed some of them, to not be visible anymore into Swagger.
I have try with #Hidden, #Ignore, #Operation(hidden = true), and so one but those Classes are still visible there. Any idea ?
Have you tried #Schema(hidden=true) Pojo classes that are used as input or output typically ends up in the schema model. For methods that represents an operation, #Operation(hidden=true) should work
Related
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.
My use case is as follows:
I generate the OpenAPI-compilant specification in json format using SpringFox Swagger2 in my Spring Boot application. During configuration of Docket bean I use its method additionalModels() to add a model that I'd like to document. This model is not explicitly used by any endpoint.
Upon inspection of generated /v2/api-docs as well as swagger-ui.html I can confirm that this model is properly placed under the "definitions" property alongside all other models.
On the other hand ReDoc only seem to render the endpoints and their explicitly used models and responses. Can I somehow force ReDoc to render that one additional class? Like, for example, somehow referencing it in the API description?
I am not sure, but I thinks it's related to this issue. If that's the case and it's not possible at the moment with ReDoc - what would be a reasonable alternative with similar look and feel?
ReDoc author here. This is not yet possible in ReDoc but support for this will be added in the future.
I can't come up with a reasonable workaround at the current stage so stay updated by subscribing to the issue you referenced.
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.
Is it possible in GWT 2.4+ to disable obfuscation for certain java model classes?
The reason I am asking this question is we use GWT RPC to talk to the server and need to store these objects returned etc in local storage using the Indexed DB API, we are currently using websql api. If GWT obfuscates/renames your properties etc then this renders using the Indexed DB API useless in your code.
Maybe there is a way to ask GWT to replace a property string with the obfuscated version in your Indexed DB api queries?
I could create a whole new java model that uses javascript overlays so these are preserved when GWT compiled and replace GWT RPC with JSON RPC but this would be a lot of work.
Any other ideas would be appreciated!
I also looked at the AutoBean framework which produces nice JSON output of your model interfaces but I don't think has a nice simple javascript representation under the hood.
You can set GWT Compile style attribute to PRETTY or DETAILED. so that GWT will not replace the class, method or variable names. For more information refer this link.