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
Related
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.
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.
How to mock HttpRespose? I am using scalla, akka with spray for calling rest service which respond with json, I need to write test case for same. suggest me the technology that can be used.
The best option would be to use Spray Test Kit
http://spray.io/documentation/1.1.2/spray-testkit/ which comes with predefined methods which allow for some mocking.
If you need to mock an underlaying library Mockito is a grat choice but there are others like Scalamock you could give a try.
For JSON checking I had good experience with using spray's json library and checking on the deserialized object.
Mockito is still for me the best mock-utility (see http://site.mockito.org/). It's written for and in java, but I find it works very well with scala. Another good one is easymock (http://easymock.org/).
You should also evaluate whether you need to go so low as mocking HttpResponse or if you can let your tests operate on a higher level than that.
I try to answer to the title:
how to write test case for rest service in scala akka(spray)
It looks like there are missing points in the detailed description of the question...
It worth to mention that there are different levels of tests we usually write and I would suggest the following:
for unit tests (no actor specific) mocking there many options that not different from usual suspects we have in java (Mockito, EasyMock, JMock) + some scala specific (like ScalaMock). Scalatest provides a sugar wrapper for some of them so I would recommend it.
on integration tests level I would mention akka-testkit which is the best option to verify actors behaviour by exchanging messages. Also as mentioned in previous answer there is spray-testkit which makes testing of route logic easy.
for service/component level tests (send http request and verify the http response) you can use any usual testing library like Scalatest or use more complicated one for writing business oriented tests like cucumber. There are also some options to mock/stub dependencies like: mock-server, wiremock, stubby4j which actually can be used in any language but the question mentions scala so jvm running options should be preferable. From my experience mock-server is the most flexible option here.
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.