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.
Related
Supposed you need to interact with/integrate 5+ different web service sources instead of tables from the database.
In first lane each WS supports read methods like search,list and single view (in short, no CUD from CRUD). Write access should also take place later.
What would be your approach to integrate those to extbase?
I'd like to stick to the conventions of models and repositories. In this case, i think we need to use Models and CustomRepositories. Should the repositories interact directly with the webservice or should we think bigger with an PersistenceManagerInterface implementation and extending the Generic/Query to e.g. paginate on the results by extbase conventions? What is about TypeConverters and PropertyMappers for linking between controller actions with the models "as parameters".
How could a mapping from JSON to the models look like? A TCA configuration is required for the DataMapper, but this is not available because no DB is used, so it cannot be used.
Where should you start?
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.
It appears most of the WebAPI examples are returning some models (either domain models or particular view models).
When using domain models, we actually request more data than needed in the view from ajax calls, and then build our view models using JavaScript (assuming we are building a web app).
I tried using different view models for each page (view), which allow me to reduce the network footprint and return only the fields in need. But in the ApiController I would have too many GET methods. And it is impossible for us to predict the future need and build an API returning all kinds of view models.
I would like to mimic the Facebook Graph API and build a uri like:
http://... api/games/333?fields=id, name, price, imageUrl
And our user should be able to update the record with only these few fields.
A detailed description can be found in a google code blog entry: Making APIs Faster: Introducing Partial Response and Partial Update.
Some other posts here suggest this is beyond the current ability of ASP.NET WebAPI. Will ServiceStack or some other package help us achieve the goal?
Try this project: https://github.com/AnthonyCarl/ServiceStack.PartialResponse for the partial response side of the question
ServiceStack.PartialResponse.ServiceModel
Google Style Partial
Responses for ServiceStack.Net. Currently only the following Content
types are supported:
application/json
application/jsv
text/html
application/xml is NOT currently supported.
I wanted to implement this as a ServiceStack IPlugin, but I was unable
to figure out how to get the access I needed to the response DTO for
my approach. Currently, this is implemented as an IRequestContext
extension.
Providing Field Selectors
Field Selectors can be passed using the header or query string. By
default field selectors are combined form both. Duplicate field
selectors are reduced. The field selector is applied to all entries in
a list if the selector refers to a list.
There are a couple of options to implementing partial updates in ServiceStack. See this question about implementing PATCH requests for an approach that uses a request DTO with nullable values, and the PopulateWithNonDefaultValues and similar extension methods in ServiceStack, to take a PATCH-style request where the client can send any subset of fields in the request body. If a given field is not present in the request body, then that property of your domain object will not be updated.
If you really need to use a query string to specify the subset of fields that should be updated, then you can still use the approach described above, but add some code that first nulls out any values in the incoming request DTO object that are not named in the query string. Then you can again use PopulateWithNonDefaultValues to copy the remaining values to the domain object.
Also, to comment on another part of your post that is closely related to the recommendations I just gave:
When using domain models, we actually request more data than needed in the view from ajax calls...
Here is where a message-based design is helpful: model your request/response messages as separate DTO classes, instead of reusing and exposing your internal domain model objects. Among over benefits, you'll eliminate the problem of exposing unnecessary fields in your request/response models. Message-based design is one of the core concepts that drives ServiceStack's implementation. You could, though, achieve similar results with Web API or MVC. I highly recommend reading this article that discusses how this design works in ServiceStack.
You can use OData Protocol,look this example.
It's can use key:$select,$expand,$filter for search,select some fileds.
Most important,the ASP.NET WEB API has a SDK for support this.
I use Struts2 + Spring + Hibernate for web site development. And I am wondering about 1 thing, I never used annotations in my web applications, but hey, what is the best way to code a web application? Annotations (I never understood how they works) or Config-files? and why? More complex applications will work faster on this?, or is something about principles?
This isn't definitive it is just what I do with similar tools.
Looking at the Struts2 xml configuration vs conventions (struts2-conventions-plugin) and annotations. The benefit of the later is that there is a lot less work. When the conventions don't do what we want we have a choice, use struts.xml which will override the conventions or use annotations which will also override the conventions. If you go with annotations on your action class then you can clearly see what is going on from one location. With struts.xml you often need to look at both the configuration file and the action to understand the whole picture.
Although I advocate annotations, the xml configuration is still good for somethings. It is a good place to set global parameters. It is still needed for defining custom interceptors/interceptor-stacks and if you need actions defined from wildcards it makes sense to have them there too. All these examples reinforce the point that it is more general configuration that belongs in struts.xml because they are bigger than any action.
For hibernate it is similar. Your entity classes and meta information are all in one place which makes it easier to understand. There was a case I had where xml was more useful in a testing situation, I needed to use the same entity classes but needed to make extensive changes to the metadata. So in that case I could simply load a different set of xml files.
With spring I use annotations for injection but wire the beans in application.xml.
Other stackoverflow posts that may be of interest:
Xml configuration versus Annotation based configuration
Is there a good reason to configure hibernate with XML rather than via annotations?
We've used the Validation Block of MS Enterprise Library for some time with great success in conjunction with custom DALs but we've recently started using the Entity Framework and can't get the Validation Block to work with it. The objects are dynamically created in EF and putting attributes on top of them will simply get wiped out when the models are re-genned.
Can these two co-exist? If not, does anyone have any recommendations for what validation library/simple rules engine would be a good candidate to use along with EF?
Thank you.
You need a validator which supports a "buddy class" (like this example for Dynamic Data). This seems to be a work in progress for VAB. I can't find an example of anyone actually using it yet, but it might work.
Validation Application Block supports the concept of configuration based validation. This way you can separate your generated domain entities from validation. You can use the Enterprise Library configuration tool for this. Simply right-click on your configuration file and start adding validation configuration.
I advise you to read the VAB Hands on Lab document (ValidationHOL.pdf) which is included in the Hands On Lab download. After reading that document, read this article. It explains how to integrate VAB with Entity Framework.
Good luck.