I'm looking at the documentation here, and all the examples use
MockMvcBuilders.webAppContextSetup
I tried these examples with
MockMvcBuilders.standaloneSetup
and it seems to work. I feel like the latter is preferable if you can get away with it. Does this somehow degrade the functionality of spring rest docs? Why wouldn't I want to do the latter every time? Why doesn't the documentation use the latter?
I chose to use webAppContextSetup in the documentation as I wanted to encourage people to document their API using the complete implementation of the service. If you use standaloneSetup pieces may be missing or mocked out. It's possible that those differences will lead to inaccuracies in the documentation.
That said, you don't have to use webAppContextSetup. As you have observed, Spring REST Docs will work with standaloneSetup too. If you are confident that the environment that you create using standaloneSetup produces the same behaviour as webAppContextSetup, then it can be a good choice as it'll reduce your tests' execution time.
Related
I want to automatically document my REST-API. I know, there are many tools for that, but I want to generate the documentation from my unit tests.
The reason for this is, that I want the documentation to mirror, what is tested and what not. Nevertheless the documentation should be as rich as a documentation generated by let's say swagger.
I already found two projects with this approach, doctester and testdoc4j. Both do not satisfy my needs. The resulting documentation does not aggregate the happy path and the error paths.
What tools do you use and can you suggest any good one?
Cheers.
Edit:
There is a difference between documenting the API contract, defined in the interface, and documenting the test scenarios. If my documentation only includes the tested endpoints and pathes, I am able to define my interface and can hand out only the portions, I have tested.
This means I am able to define an interface with let's say ten endpoints. After implementing a basic functionality with corresponding tests, I can release this part with documentation. Not yet stable or implemented endpoints are not included, which prevents the users from using them.
Perhaps you want a BDD framework? Eg:
cucumber
fitnesse
jbehave
I recently did some research about the same topic and decided to use the free version of Miredot because it is the only tool that fulfilled my requirements:
Does not need extra annotations. All information is extracted from JavaDoc
Can handle JAX-RS as well as Spring annotations
Easy maven integration
Miredot generates automatically a HTML based documentation when you run mvn test
Swagger is a beautiful option. It's a project on GitHub, has Maven integration and loads of other options to keep it flexible.
Integration guide: swagger-core wiki
More Information: here
Not sure if you have already found something for this, but Spring RestDocs does exactly what you are asking about here.
https://spring.io/projects/spring-restdocs
Im curious as to other tools you may have run across in other languages too.
I'm trying to figure out the best way to have my API documentation be the source of truth and use it to validate the actual Java REST code ideally through integration testing or something of that sort. We're using the contract first or consumer contract type of approach, so we don't want the documentation to be generated from annotated code necessarily and updating every time a developer makes a change.
One thought has been to use Swagger, but I'm not sure how best to make it be used for validating the API. Ideally, it'd be good to have the validation occur in the build or integration testing process to see if the real response (and request if possible) match what's expected. I know there are a lot of uses and tools for Swagger and just trying to wrap my head around it. Or if there is a better alternative to work with Java code.
Recently, we (swagger-codegen community) start adding automatic test case generation to API clients (C#, PHP, Ruby). We've not added that to Java yet. Here are some example test cases generated by Swagger-Codegen for C#:
https://github.com/swagger-api/swagger-codegen/tree/master/samples/client/petstore/csharp/SwaggerClient/src/IO.Swagger.Test
It's still very preliminary and we would like to hear feedback from you to see if that's what you're looking for.
I think you should try swagger-request-validator:
https://bitbucket.org/atlassian/swagger-request-validator
Here are some examples how to use it:
https://bitbucket.org/atlassian/swagger-request-validator/src/master/swagger-request-validator-examples/
Another alternative is assertj-swagger:
https://github.com/RobWin/assertj-swagger
You may want to look at Spring Cloud Contract. It offers you a DSL, where you can describe the scenarios (more or less what is the response I get for a given request) and it seems to fit well to what you described as a requirement...
If you're using the Spring Framework, I'd highly recommend checking out Spring RestDocs which allow you to generate
I know this topic may have been discussed here regarding making java annotations that have logic functions and do specific actions based on conditions.
One of the famous examples of course are junit and hibernate.
I have also seen annotations that when you place on an api of a web service controller that it checks the header for authentication token and if the user was not authorized it would return unauthorized and would not even enter this api.
Also i have seen an android library that does most of the normal application logic with annotations: http://androidannotations.org/ .
Now all of the tutorials i have seen in the internet regarding this topic don't give clear examples for how to implement it with least code and i find in the end that extra code is written which conflicts with the main purpose of using annotations with logic which is saving time in writing more code.
Take for example in this reference http://androidannotations.org/
#NoTitle
is equivalent to
requestWindowFeature(Window.FEATURE_NO_TITLE);
in this example they seem just to inject their annotation library , they haven't changed any other thing or added any extra code like for example changing the base class which is activity.
Are things just abstracted too much?
And if so how can i reach this level of abstraction to make something like the android library i mentioned above.
Any design patterns recommended for this?
The example that you mentioned, i.e, http://androidannotations.org/ in fact a good implementation of the annotations.
In your example, the Android runtime must be assigning the values to the properties(objects) during runtime, based on the Annotation specified. Methods also can be picked up for execution based on the annotations specified on them.
Annotations, is a simple but powerful concept in Java. You can simplify the usage of your api to a large extent.
Check this post https://devcompass.com/2016/05/08/java-annotations-converting-java-objects-to-excel-data/ for information on how to create annotations from beginning. Checkout the source code zip file at the end of the page.
Trust me, annotations are very simple to learn and they can make a big difference in the source code implementation.
I came along the Drools fluent API which, as far as I understand, allows Rules to be added/edited/deleted from working memory at runtime.
The documentation mentions it here without going into details:
http://docs.jboss.org/drools/release/5.2.0.Final/droolsjbpm-introduction-docs/html/ch02.html#d0e124
Does anyone have example code on how to use this API?
I am specially interested in adding/changing/deleting rules at runtime.
I think that section was speaking more to the fact that they have a programmatic way to create rules. I was under the impression that the "fluent" part referred the their use of the builder pattern that allowed you to string methods together in the same way a rule would appear.
But yes, you are able to change/edit/delete rules dynamically for a particular KnowledgeBase. An example can be found in their sample integration tests, or consult the KnowledgeBase docs - particularly the addKnowledgePackages(Collection<KnowledgePackage> kpackages) and removeRule(String packageName, String ruleName) functions.
I suppose you can combine the DescrFactory with the rule addition/creation. I'm not really able to find a public API anywhere that will help you with how to use it, and it's in the drools-compiler dependency, so I'm not certain that there will be one published as much of that artifact is meant for drools internal use.
There is also another related S/O discussion about this here.
Say you have an application with a series of actions. How would you write it such that actions are logged when they are triggered?
Use a Template pattern.
Use AOP.
Use a Listener and Events.
Use a combination of the above.
Something else (explain).
I'd vote for AOP for the sake of eliminating redundancy, but only if there's room for AOP in your project.
You can have custom logging using a logging library from your methods elsewhere in your project, but in a particular component where you hold many similar classes and want to log similar things for all of them, it can be painful to copy/paste and make sure everyone knows how to log.
EDIT: regarding the other enumerated approaches, I think the advantage of AOP would be that it doesn't require you to design your code (template methods or events) specifically for this topic. You usually don't lose any of the code flexibility when spotting cross-cutting concerns and treating them as such, as opposed to redesigning a whole class hierarchy just to make use of consistent logging.
I think the best answer is using log4j (or sli4j, if that's the latest) inside an aspect.
Logging is the "hello world" of AOP. If you aren't using AOP, you're doing it wrong.
It really would depend on your specific context. Specifically on what was being tracked and how the application currently worked. If the actions are classes that all have a common base class and all you care about is the name of the action, then a simple addition to log in this class would be a great choice. If you have actions spread across several layers of code, then an AOP or Listener/Event type solution might work better. If that application was a web app vs desktop or if you ultimately need the logs feed to a database, webservice, or just want text files all make a difference.
if you simply want to log particular actions it's probably simplest to use a logging api such as commons-logging or log4j etc add a log statement in the code you wish to track.