Comments (12)
I should add the default behaviour of the Swagger converter described on my blog. It sets default values for Swagger fields. Regarding responses, it uses the most top response, assuming this is the happy case (200, 201). It assumes that the other responses are error cases. Issue: #4
Regarding examples, there is this repo (or do you mean something else by examples section?):
https://github.com/SvenBayer/spring-cloud-contract-swagger-sample
from spring-cloud-contract-swagger.
Yeah I meant examples
inside a Swagger definition
from spring-cloud-contract-swagger.
Have a look at param_swagger.yml:
https://github.com/SvenBayer/spring-cloud-contract-swagger/blob/master/src/test/resources/swagger/param_swagger.yml
There you have example and x-example fields (properties) for variables of the definitions. However, the values are stuck to the definitions and will be used for both, request and response. If you paste the param_swagger.yml to editor.swagger.io, you can see for each request/response the example values.
I hope I understood you right this time? 👍
from spring-cloud-contract-swagger.
I hope I understood you right this time? 👍
Almost ;)
Contract test requires a scenario. Given this request you get that response. Swagger gives you a schema - these are all request fields, these all response fields, these all possible status codes. Without an example section where you show an example of usage you're basically creating a contract with all request fields and a random status. You're not really showing how to use your API right? Or am I missing sth?
from spring-cloud-contract-swagger.
Yes, partly. You can create with the example and x-example fields already some half-meaningful values for your request and response. However, it will only show you how to use the API on a syntax level but not on a semantic level.
Also you are currently restricted to one use-case per method/endpoint and as you said, all values will be send.
You could create a proper example by adding an x-example property to the schema field which represents a body in the response and request. Then, you could create a use-case that also exists in reality.
I see two actions for improving this framework:
- We want to exclude optional values in requests: #6
- We want to have scenarios that exist in reality: #5
Is this what you mean by example? I think this will enable real examples, right?
It is probably very difficult to enable more use-cases than one per request.
from spring-cloud-contract-swagger.
Yes, partly. You can create with the example and x-example fields already some half-meaningful values for your request and response. However, it will only show you how to use the API on a syntax level but not on a semantic level.
Again, you're talking about example of a field. I'm talking about example of a pair of request->response. Example like:
given: request with JSON `{"a":"a","b":"b"}`
when: POST at /foo
then: status code 200
and: body with field `{"a":"a","b":"b"}`
I don't care what all the possible inputs on the request side are. I wonder if that's even possible with Swagger (that's why I don't know if Swagger is a good choice for contract testing).
I have an incubator project for RAML that does sth similar - https://github.com/spring-cloud-incubator/spring-cloud-contract-raml
My conclusions were that you need 1 RAML per interaction and you need to use the default, example values. So maybe that's very similar to what you're saying actually.
from spring-cloud-contract-swagger.
Swagger is like a collection of RAML, so it contains several endpoints. It is pretty similar to RAML. In Swagger you can add everywhere any new fields with an x- prefix, similar to the default fields in RAML. Like x-imaginarifield
Yes, you are right, Swagger is not a good choice for contract testing. Using Groovy, JSON or Yaml would be a lot better for specifying your API. Swagger should be generated by the Microservice.
However, some big conservative companies stick to defining their API with Swagger instead of using proper contracts. Therefore, instead of defining the API in two separate documents, maintaining those two documents (Swagger + contract) and risking inconsistency, it is better to define them in one document. This way, we can take at least partly benefit of CDC. That's why I created this library.
Yes, it is like with RAML. But since Swagger is a schema, you can only define one scenario/interaction per defined endpoint. Defining more scenarios within one endpoint definition would be possible but too confusing. This is because your example is mixed with your schema definition.
Did I get you now? :)
from spring-cloud-contract-swagger.
However, some big conservative companies stick to defining their API with Swagger instead of using proper contracts. Therefore, instead of defining the API in two separate documents, maintaining those two documents (Swagger + contract) and risking inconsistency, it is better to define them in one document. This way, we can take at least partly benefit of CDC. That's why I created this library.
I see, so maybe it's worth writing about it? And actually suggest to go the other way round. Create contract definitions and generate swagger from it?
Yes, it is like with RAML. But since Swagger is a schema, you can only define one scenario/interaction per defined endpoint. Defining more scenarios within one endpoint definition would be possible but too confusing. This is because your example is mixed with your schema
Can you have multiple Swagger files instead of having everything in one?
from spring-cloud-contract-swagger.
Thanks, I added a recommendation to the Readme.
You could have one Swagger file for each request, but I think the general practise is to define your API for a Microservice in one Swagger document. I think, if a company sticks to using Swagger for API specification they will stick to define all APIs for a Microservice in one Swagger file.
I already had some ideas of how to enable multiple scenarios, like enabling a x-401 etc parameter that you can add to enable a scenario for a 401 response. But this could be a bit confusing.
Another solution would be to write a Spring Cloud Contract Swagger Verifier that checks if your Groovy contract and Swagger file are compatible. Maybe this could enable projects to move from Swagger contract tests slowly to Groovy contract tests over time.
You can see at https://editor.swagger.io/ an example Swagger file and on the right. If you add example, x-example, default fields, they appear on the right too.
from spring-cloud-contract-swagger.
I don't know if that's useful but there's also this - https://bitbucket.org/atlassian/swagger-request-validator . We do generate a wiremock mappings so you can assert whether WireMock is compatible with given Swagger spec.
from spring-cloud-contract-swagger.
Ah yes, this would be one's choice if you want to take advantage of Spring Cloud Contract and combine it with Swagger. Then you have two maintain two separate documents.
It looks like you could also use the swagger-request-validator for moving from Swagger "contracts" to proper Spring Cloud Contracts. Depending on how detailed you want to use CDC.
from spring-cloud-contract-swagger.
Closing this question as it seems to be answered. @marcingrzejszczak thank you a lot for your ideas. Feel free to open any new questions!
from spring-cloud-contract-swagger.
Related Issues (19)
- More detailed testing 2nd step HOT 1
- Add min & max values to query parameters HOT 1
- Test Swagger in JSON format
- Unify value evaluation HOT 1
- Increase test coverage HOT 1
- External files for body specification HOT 1
- Validate example values HOT 1
- Number is floating-point
- Path Variable x-example values are ignored
- Swagger name produces bizzare WireMock mappings
- Converter fails when response is an array of known response types
- StackOverflow when response has a circular dependency
- Add default behaviour of Swagger converter to Readme
- It should be possible to set real data for bodies
- It should be possible to set leave out optional parameters for a request
- Add spring-cloud-contract 2.0.1.RELEASE
- Add CI HOT 1
- More detailed testing 1st step HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from spring-cloud-contract-swagger.