Documenting RESTful APIs with Spring REST Docs and RAML by Mathias Düsterhöft @ Spring I/O 2018

[Music] all right welcome everybody I'm really happy to see you this early in the morning after the party for API documentation that's awesome I'd like to be talking about documenting restful api eyes with spring rest locks and that's there's going to be a little introduction on that like one third of the talk and after that I would like to tell you how you can add Randall to this whole scenario and why this could be useful I'd like to be giving this talk along telling the story of the development of our own API documentation and before we jump in I would like to give you some some context of where I come from I work for a company called I pages we are based in Hamburg in Jena and in Barcelona and we are offering software as a service ecommerce solutions so we target small and medium businesses and you might not know he pages despite we have quite a decent market share in Europe that's why because we sell mostly through a resellers so we have partners that sell our products under their own brands and yeah basically that's why he pages is not known to too many out there when I joined a pages I was assigned to a project that was to build a new e-commerce back-end a greenfield project where I started and we are using Java technologies Kotlin recently it's a micro service architecture and we use all kinds of spring stuff in there and one constraint that we had that is especially interesting in the context of this talk is the IP I first constrained so we were to develop a back-end that was not serving a UI only but it's there as a primary feature of the product that makes the whole back-end open and that lets not only serve our customer through your eyes but we can also build new great things with partner so that was the idea it's also why we pretty early started thinking about API documentation because we knew the API would be such an important part of our product so we were thinking how to how to tackle that one and we came across spring rest locks quite naturally like we are pretty much using a lot of spring stuff and spring rest locks was new and interesting back then and we liked it from the start and mainly we liked it because it takes test-driven approach to documentation and this test driven approach gives you nice nice guarantees in terms of accuracy of your documentation I think many of you have worked with API documentation and if it's disconnected from the code it's it basically rots away like it's hard to keep it up to date right so from this experience we really liked the approach that spring rest Docs takes the step test of an approach where you can omit certain parts of your documentation generated in tests and then you bright handwritten documentation with asciidoctor which is quite a nice markup language and it's easy to write so that's the approach of spring spring rest dogs takes handwritten documentation that can use generated parts that come from the tests another interesting aspect was that we'd like to tool that we would like to have a tool that integrates nicely with the way we test our rest endpoints in our services and the tool that we use is spring MVC tests or spring what can we see I don't know it's like interchangeable names there and spring rest Doc's really supported really nicely it supports different things as well like rest a short but we use it with maken BC can you can you still hear me like I have the feeling yeah okay okay great so I would like to introduce you to spring Red Sox with a little sample product I prepared something to walk you through how this usually works I prepared an e-commerce application of course so it's really complex business model here we have a product that's basically a JPA entity and it basically just has a name in the price right so it's really basic you also have a cart and the cart is basically just a list of products alright so we have you have a list of products and then we have a total price that's it nothing nothing fancy there regarding the rest API you don't see your controller here so for for the product so we used to bring that arrestee to expose a REST API on top of this product repository just yeah because I was lazy at that point but I came up with a custom controller for the cards resource so we have a controller for for the carts resource and this can do four things that can create a card with a parameter list post it can get a cart by ID we can order a card like place an order out of a card and we can have products to it alright and adding products it's done like it's in Hetty or hypermedia based API so we can post product arrays to this endpoint and then this worry is used to look up product entities and and these are assigned to the cart so also pretty straightforward API and now we're interested in the tests right so that's where the documentation is supposed to be coming from so let's look at that as I said we use in our test the mock MVC framework and basically and what can we see who knows that we work with that alright so almost almost everybody you basically it's centered around this mock MVC object you can auto wire that and with spring boo tests help and then you can use this object make requests like let's look at this should get card so we need a card with a product first in order to retrieve it so that's what we are putting into this test fixture here we are also using the REST API - - to prepare our our fixtures and then we go use the mock embassy object to perform a get on this end end point and we get better good result actions object that is basically just there to to add assertions now right so you can use that as a fluent API so I could just go and and put my assertions directly after this request but I'd like to do it a little bit differently like you have to separate in a test so the assertions come here so we can check status is okay I have certain response structure so great we have an API and is working the tests prove it's it's working it's all nice but who can use this API right it's not approachable we don't have an have an API documentation so let's at that let's add spring Red Sox to the game and what you usually do in spring when you start something new any guesses put annotations right so Auto configure Red Sox is the annotation that we need here it gives us same defaults for the Red Sox configuration you can do it differently with Jayant rules and setup methods but this is the most convenient way and now all we need to do in the most basic form is register result handler so we go and do the pass a result handler here this result handler is given by spring Red Sox it's called document static factory method where we can just pass a pass an identifier for the operation that we want to document right so that's it I do that for for all my tests where wonder documentation two cards get and last but not least card order and once we have that let's see what that gives us so let's run the test let em spring Red Sox do its work and look at what's generated test this green that's good didn't mess up here and now we see a new folder here in the build folder generated snippets that were where spring Red Sox puts the generated parts of the documentation and we get folder here that's basically this identifier that we specify so we get a bunch of files there it's all just we didn't provide much information right it's just as identifiers so all spring Red Sox knows at that point is the rec fest and the response that was flowing and nothing nothing more so it can basically just derive that information into in two different forms and it does that by for example here having an ascii doctor saw snippet that is telling us how to do this request in curl we also get it for HTTP which is a much nicer command-line rest client we also get it in HTTP notation and we get a sampler recurse body which is MD response body and it's all wrapped in an asciidoctor source code block right so this is write quite a lot that we get by just putting a result handler does not much work but we can do even better and this i prepared as a separate branch just to spare you some some looking at me typing so things will happen here so you see now that this document method became a little bit more complex right was a little bit more effort we can register despite the identifiers we can reduce the snippets that's basically just a way to snip it as a way to document a certain aspect of a request right so here we documentaries response fields and when we start doing that we have to document all the fields in that request in that response right so we give what's bring rest Doc's calls a fear descriptor that's also all done by static factory methods filled with past so there's a field at total that's adjacent path expression there can be more complex as you can see here and then you can give in just a description I could tell what this field is all about okay and for links basically the same like we have links in our response and you also need to document them let's see what happens when we execute the test again mr. green and there should be some movement in this in this folder here you see now we get you new files we get a response fields asciidoctor or table that is basically just the information that we gave like the JSON path and your description but also an inferred type is it's inferred from the JSON response right it looks at the jason and you can tell the the adjacent types of that of that field in the response same for the for the links so we get tables there and now we have quite a decent amount of information in these generated snippets and now we want to put it together to a service documentation so that's done as i mentioned by handwritten parts so I put my hand written documentation in source das Docs asciidoc that's the default location and then yeah there you go so this is basically my entry point to the API documentation it's a plain asciidoctor file with some header information we won't go into details there and we have some includes and I choose to separate the different resources and different files just for for the sake of overview so let's look at the cards so we have all the four resources that I put here or that are endpoints that are documented for everyone I have a heading and then I use something that's called operation right this is a asciidoctor macro that spring rest Docs provides it's just there for convenience to help you not having to include the same files over and over again which gets a little tedious error-prone and annoying so we have this macro we can say okay please include the snippets for the operation called cards create and then please include the snippets called HTTP requests an HTTP response and for our get card we had more snippets right we want to also include the request the response fields and the link snippet okay now I have to look one thing up I think I'd made a mistake no I didn't great so great this ask you doctor and now we want to see some something shiny right so we want to see some HTML and that's rest Doc's uses the asciidoctor Gradle plugin to convert this asciidoctor files into HTML we can just go and call gradle w ascii doctor and the ask you doctor task depends on the test tasks so first all the tests are run and once that's done we have all these snippets generated and then it goes over the sauce Doc's ask you doctor folder and converts it to HTML and now in build asciidoc html5 index.html we see a new file which is now my API documentation in an HTML format so we see we have the cards and we also have the get card with an example request sample response response fields endings right so that was I think quite a quick and thing I forgot my favorite feature right so I will jump back to the code and show you something something else which is the last point of this little introduction these response fields aren't just there for providing documentation information there are also assertions and that's really nice so I said that gives you spring rest or gives you much in terms of accuracy of your API documentation so let's do one thing let's say I document here a field subtotal and by doing this I do two things I talked to him in the field that doesn't exist in the response and ID I forgot to document the total field right so the test will now fail on me this is expected and spring rest locks tells me nicely that the following parts of the payload were not documented the total field right and it also tells me fields with a following path we're not found in the payload subtotal right so whenever I evolve my API at new fields I change field names I remove fields my test will start failing if I forget to update the documentation which is really nice so you have strong pretty strong guarantees that your documentation is accurate you can still forget to document resources but yeah that's that's what spring rustic doesn't cover so this is really nice from my point of view and we would just went with that right so we put that into into place for all our services and then we were trying to get a public API documentation out of it and there were quite some challenges on the way to a public API documentation from what we have seen now and I picked three examples that I really find interesting and hopefully you find them interesting as well of problems that we needed to solve first any pages we have a bunch of tech writers that are really great and they help us to to make technical written documentation and and general text in general that we publish just high-quality right so developers not only write good text so they help us to improve that a little bit but with this model that we have just seen with putting these descriptions in the tests all the time we we spread all these texts across all our test code right and it's quite a bit of test code that we have and we don't run our tech writers too we have to scramble through all these tests and find these places and they actually also didn't want to tamper with source code files so that they are okay I'm afraid to break things and I don't find my way around so we helped a little bit by externalizing descriptors so we took these descriptions out of the tests we invented a new factory methods for these few descriptors where we just have a JSON path and the field or key for a descriptor and then just descriptors loaded from a file and this file also resides in this in this source Doc's folder so we now have a folder that the tech writing department is responsible for right they own this code in this directory and they can we can also notify them about changes so you see here here's only the description but we can actually every property of the field descriptor we can put in this industry and I good one thing solved the second problem was something that I didn't really see coming it is like if you have tests that generate document then your test date is suddenly public and I think developers are sometimes they are funny with test data sometimes they are lazy with test data but seldomly they are it's something that you really want on your public developer portal so we came up with a test data catalog or ya know set of test data that you can use to pull in and use it in your test and we can also use this test data set to provision it to a real shop on our life system so you can actually see responses in API documentation that you can actually play against the real shopper tests shop and then you get similar data back then your test gift so that's quite a nice side effect of that interesting thing like as I said we are working in a micro service environment so have many services that contribute to the public API documentation and in the end we of course want one documentation to present to the user right you shouldn't see that aspect of micro services so we need to do some work in order to aggregate that back into a single API documentation and we use our CI or continuous integration and continuous delivery infrastructure for that what we do is like on the left hand side you see a bunch of services that we have like we have more but these are just examples and every service that emits public API documentation builds a separate jar in the build face whenever we merge two master we would do that and we would put the source Doc's asciidoc folder into the jar and also this generated snippets folder so everything asciidoc regarding API documentation is going in that folder and we would then in the continuous delivery pipeline where we deploy to production at the very end we would download all these jars for the services that are relevant we would extract them and then we have a top-level asciidoctor file in a separate repository that pulls these parts in and aggregates an up-to-date API documentation of what we just deployed so it's also this accuracy is not lost we were really paying attention that we don't lose these guarantees of accuracy because we are not playing nicely in the in the deployment process so whenever something is deployed to production we also update and publish this API documentation okay so these problem solved we were then really having a first achievement we had a documentation on our developer portlet right so that was was a nice moment I'd like to show you just what we came up with this is the API documentation so far to be honest it's really just an API reference at the moment we are lacking some process description some use case descriptions that walk you through some common use cases it's really just a listing of resources that we offer and it's quite a quite a bit of them and also by the way if you'd like to play around with that API here's a link to sign up for a forest shop and for a test shop and and work with that so basically you would be getting there from our developer portal and then Doc's beyond API is where our I was just looking at so that was that was nice so we had a good starting point to actually work with partners we could exchange knowledge about our API with partners that's great but we had the feeling that there is this is not if not enough like we had we had the feeling we wanted to go a little bit further we want something that is a little bit more nicely what we've just seen its pragmatic it's full of information but it's not right it's not picking you up is it like it's a little bit more appealing like we wanted that something that is a nice appetizer to directly start using our API so we had the feeling we need something that is interactive right the documentation we can look at informations about the resource but at the same time start interacting with the API right away play around with it right away and this is something that we had the feeling we couldn't achieve and basically this is because we have in this asciidoctor approach we are mixing information and markup right so we always have this asciidoctor snippet and it's hard to process that any further of course ask you doctor can process it or transform it to HTML but like really parse it and do something else out of it it's really hard so yeah we had to feeling that with the asciidoctor and spring Red Sox click playing approach we're not getting anywhere beyond studying at HTML that I've just shown so we had the idea what if we had an machine readable API description right something that's more abstractly describing our API this would be awesome and then surprise there's already something like that yes Rommel and we can use it and we actually had some expertise in the house already about Rama so we just picked it up we didn't really look at competitors there are tons of them out there like open API and API blueprint are just to name a few and Rommel is restful api modeling language it's a basically Yama base specification to describe requests or to describe a REST API it has two versions of specification zero eight one zero and usually this company mules office behind drama but and usually these companies that try to offer whole lifecycle of tools around api's so we are just focusing on the documentation phase right they they do tons of stuff on on top of that the simplest example of a rama file is this so you basically have a little header block here where you can give a title and also some other top-level information about the api and then comes the resources part that just lists the resources you can also hierarchically list them right nest them and here we have this degree tinks resource that exposes the get method responses are always 200 that's at least what the documentation says that's nice so and the body would be application Jason it would follow that type information the types can be something called rama datatype notation that's part of the Raman specification it's a yama based data type description format but it can also be json schema right so this is a little bit widely more widely known at and the example can also be it can be Yama or it can be Jason right so just to get an idea of what we are talking about it's a very basic basic example okay that we where we wanted to go to this rummel based approach and we wanted to keep our benefits that we already had those things that we liked from spring Red Sox this tester and approach these guarantees in terms of accuracy and we were not finding anything that helps us there so we were building our own source project called Red Sox ramen that was solving that so we with that we can keep everything we like from spring Red Sox and at the same time we can get a run a description of our API good so this is screenshot from the repository it's living under the pages - te organization Red Sox Romulus it's name here's the screen tour of the readme file so there's quite a bit of documentation there this also links to the guitar chat - to start interacting with us yeah so I would be really happy if you would pay a visit to that repository and even try it out but to make sure you get a glimpse I would to show you some something with that Red Sox ramen now I would like to use our sample project in the state that we left it and addressed ox Rommel to it and get run out of it and then show you how great it is to have a ramen based description of your API good so let's continue here we had as I said we had tons of these tests like just like this one quite a quite a large code base and then we were wanted to introduce Red Sox rommel and then we said okay this is quite a bit of amount of refactoring that we need there it's quite tedious and it's quite boring let's invent something that's a little bit smoother right and what we came up with is oh yeah bet by the way I already have to build set up here maybe we look at that in a bit I would just jump directly into the code for that so we had you have tests like that and to refactor that test to also apply rest Doc's Rommel we have to do just one thing no it's not putting in a notation it's deleting the static import here and bringing in a new one so we just bring in the rumble documentation document which is coming from from Red Sox Rama and yet that should be that should be already it so if I just run my test again we will see what happened what it additionally gives us actually these this new document method it's something like delegating to the old one but it's also interests in respecting all the information that we have in the snippets its extracting these field descriptors and trying to put them into another snippet our own snippet right so this Irama and description of a resource is caring about a lot of aspects right it needs path parameter so it needs query parameter that needs to have knowledge about request fields about response feels about headers all that so and usually you scatter that in two different snippets and spring Red Sox and we get all this information everything that we can can get hold off in this snippet block and put it into our own snippet we will see that a little bit better in the next step but first let's see how what it what it gives us and as I promised it looks a little bit similar to what we have just seen right it's the same snippet still there and we have some new files on top so we have this rummel resource dot Rummel file which is a rummy representation of this particular resource it's not really real valid from a file it's just a fragment and it's basically just describing that resource it's looking at the response it found and it just puts all the information in here we have an example from the from the response that we record it and we also have because we have this response fields block in the documentation or in the in the tests we will get also schema files so we take this few descriptors and generate as a JSON schema out of it okay so this is the first step in applying restocks rama's who just swap out an import would be one way if you are an ex if you are on a new project then you might want to do differently you might want to go with Redsox rama right away and that's also possible then you could just use our snippet directly right this is the snippet that would be emitted in the version that we had before transparently for you by getting all the information from the from the call that you made so here we have a rama resource snippet parameter object because now we can put very much information in it so we came up with a builder to help you to just specify what you have because all the parameters are optional but you just put what you have and then we are we go with that so at the moment you can give description you can tell us if it's a private resource or not you can give requests views response videos links path parameters request parameters and as I said all these are optional and here we just picked a few to generate that alright so now we have we have this new snippet right so every every test now emits also on top of what had already emitted a ruhmal fragment and now we want to have one Rummel file out of bid out of it right so we need this aggregation face very similar to what asciidoctor did by picking up all these and by by including all these snippets we now look at this generated snippets folder get all the fragments and try to build a API run out of it let's see that in action so Gradle the task is called Rommel talk so that's also depending on the test task it would run the tests get all this Rommel fragments and then do its aggregation work and once we did that there should be a new folder in the build folder now there it is and we get a top-level file called API Rama the name is customizable we just went the d4 here and this is how it looks like it gets some title information or some header information where does that come from right I didn't show you the build setup so let's jump to the boot grater and there's a little bit of an extension here that helps you customize certain aspects of this file you can do more it's just the basic basic stuff that I put here you can look at the documentation for what you can do else followed by the setup block we have all the resources and there we just list the first path part we extract and we we kind of structure the our file a little bit by includes this helps us to aggregate in the end multiple API rommel files again into a big one right now we have many API rommel files for different micro services and then we still need to aggregate that back into one at a later point in time so it's with that structure it's really easy right you know you just need to pick the I pick these resources and put it into a bigger file and then you have it so the structure is a little bit due to better yeah better aggregate ability later so then we have our cards rommel and now we see all the resources that our card offers so I post on cards to get on card slot IDE we have a post on card / IG / order and cards ID products we can post to add products to it so yeah so now we have a Rama file so that's great isn't it so I think it's only great if you can do something with it right so let's let's look at a little bit I'd like to take you on a little tour through the rubble tool ecosystem to tell you what we can do with this Rama file right so let's start by a - with the tool called Rama to HTML guess what it does so basically going back to where we came from right this HTML representation it's an NPM project that is provided by mu soft so NPM install Rama to HTML will give you that you specify a Rummel file and we tell tell it what the output should be there you go is that readable for you in the back yeah fine so we can see it on one on one screen so yeah that's it gives us a nice overview of our API I think it's a little bit nice and a little bit more appealing that then asciidoctor alright so at least that's my feeling it gives a nicer overview of what the API offers and you can jump in through the resources so let's see the card get that we have played around with all the time so it gives us the methods that are available for this path and then we get a little bit detail for that resource so request is not very interesting it's a get right so we just have the URI parameter that's undocumented here and the response is dead so the response will just give me now the media types and the type information so we get the json schema here and then we get some examples here okay one thing that I'd like to show you a nice feature of rest Doc's Rommels with this that I were to show with this HTML presentation is that sometimes you have different variations of resources what you offer a resource for different content types you respond with different status codes you sometimes have also data structures that are either this or that for example we have a shipping method entity and the shipping method can have a fixed price or a weight based price so it's either/or it's one the one or the other so you can't document that in one test you have you have two and then you have two examples of that test and maybe you even have two two schemas and by the way we will merge these schemas with restaurant Chronos so if you have these two tests for the same resource we would give you the multiple examples for the requests and we would merge the JSON schema so you will have come up with one and schema for that and as an example for for this I have the products patch here and because Red Sox ramen gives us multiple patch endpoints that gives us not rest Oksana Spring Red Sox gives us multiple versions of patch it gives us Jason patch format and it gives us the post to Petra's plane Jason and I have tests for both and now I would like to see that in the documentation as well so you see here requests it says okay the body can be either Jason patch Jason and then there's a schema for the Jason patch format which is not complete and it shouldn't be there right this is a specification that you should read up you shouldn't put this type information here and you have an example for this request and then followed like there's also application Jason and we can use something like this to patch it in the response I have done something I've added a documentation for an error case right so I have not only the 200 cases but I also have provoked a constraint violation and I have documented that as well because the constraint violation has a special special format so it should be in the documentation we say here now we have documentation for the 400 case for the better request case and we can see how this error structure looks like right so I think Red Sox Ronald does quite a good job in aggregating and different aspects of the resource by pulling in different fragments and making it quite concise in the in the documentation here and I think this this view here in Ramat or HTML is quite nice okay the second one is called API console it's actually something that we were keen on and to have like it's an interactive console of the API you can build it and then store directly play with your API it's also an NPM tool also provided by meu soft oh it goes something like this although I need to go to a separate folder I prepared something this API console it consists of two phases it first you have a build command that can take the ruhmal file and then generates a web project out of it that takes quite some time like it's doing all kinds of and downloads they're downloading the internet probably I don't know but it takes forever so I prepared that for you so we just need to go API console serve and then the folder that the tool generated for us and once that's there damn it forgot some cleanup here oh yeah so there you go it's up and running what and you also need to do to play around with the API and need to start my project spring boot boot run and now let's play a lot of play around with that with the help of the API console alright that's it so it also gives us a nice overview of the resources that the API offers and we can jump right in and say ok let's see if there are products there shouldn't be any because we're using in-memory database it gives us a form for the query parameters that we are not interested in at the moment and we see no products and a lot of base let's create one so we go here I already created I wanted to show you like the body is like they take the example to put it into the body so you already have something that you can and start with but of course you can you can also change that create another product alright so now you should have two products where are we there awesome now let's let's create a card card is basically just parameter lists post the other body so you have a card it has the ID one and we can now add products to this card by posting through the product sup resource here it tells us right you have a path parameter here a parameter and that we need to fill in so there's also a form for that we put the ID that we do you have seen and you also put the body you see we are posting a list of worries it's a light line separated list of worries so it works in a way that you just if you want to order product twice you put it twice into this will be list and send the request and there you go you have two fancy pans and one fancy shirt in your card and then you can go ahead and all of this nice thing is it remembers the I think it does it by name like it remembers the last value for this or parameter that you put so we still have to ID one year and there you go so I think there's quite an approachable way like you make your API into interactive and you could also choose to like deploy this as part of your static resources of your application right you could also surf this API console directly from your application which would give you really nice experience for the user so while the users edit trying to use the API you can just jump into this API console make requests against it okay um I personally like to use postmen when I interact with API so who's using postman as well like yeah the majority right there some some using poor or insomnia or something like that I still like postman it's the most powerful one so wouldn't it be great if you could import that Rommel file into postman and and make a collection out of it that would be quite nice but unfortunately postman doesn't support rummel 1 0 yet we have to i found a way the other day to do it made me quite happy so i used the tool called api Matic it's their offer api portal or the api documentation portal as a service quite a quite a nice thing you upload your ronald file or open api file or api blueprint file i generate a portal out of it quite quite an amazing thing and they have also have a transformer so they can transform from all these formats into all these formats which is quite amazing so now you're not only having everything all the tools that ronald gives us but you can also use all the other tools that's that's quite nice so yeah let's let's try that let's try that out so one thing I need to do first is to zip my ramaa directory because we have this includes and have so many files we need to upload a zip file here so I'm creating an API dot zip put everything in and now I go and use the converter by uploading this the zip file I just created and I choose postman 2-0 as a target format and that would now give me a new file is converted number five okay so I can import this file here and there you go now I have my collection of the complete API and I can also start directly playing around with it here so posting against the cards resource obviously works getting my my products also works directly straight away so this is also an opportunity I think to get a postman collection out of your API documentation this is quite a nice thing to do because usually developers built their own collection right for your API and because they want to try things out ok so that's for the demo we're already at the conclusion so I hope I got across that Red Sox Ronald is quite a neat extension to spring Red Sox that it's really easy to get it in and that it gives you quite a lot of benefits for a lab very low effort right so you can at least leverage to complete to chain of the rommel ecosystem and as I just showed you can even go further and transform into different formats and leverage the tools from other ecosystems as well so that's that's quite a powerful thing I would be really happy if you would go from here and try it out in your project you can start with the sample project that I've used here and that's available on my on my github profile but you can also get directly go through restocks rama project and here's also a sample project in is like a sub project here and this the sub project is also a sample for restaurant and it showcases a lot more functionality than in this sample project for this presentation so yeah this would be a great entry point and if you have feedback and I was really really keen on on getting some real user feedback and see what's working and what's not and if you have some some feedback please go to the Gator chat that advertised here and drop me a line really really helpful to get this out like we are using this ourselves at the moment it's deployed to all our tests but of course it would be great to know how it if it also works for others okay that's it that's all I have as I said drop me a line on guitar if you have opinions on the project also can drop me a line on on Twitter and also the e pages developer account on Twitter would be a good place to drop us a line right thanks for coming so early in the morning thanks for for your attention if you if you're having questions I think we have two or three minutes hello I would like to ask around torment maybe free questions first of all does it somehow cooperates with spring cloud contract verifier because in that project you can specify a contract and based on this contract there are auto-generated tests for your API is it somehow correlated with this no it doesn't like we're not using spring cloud contract but it's an interesting idea like it's something that we maybe can look at okay and can any of those forms like RAM be used at the component testing during contract testing between components for example by pact I didn't get that question can you can you repeat please okay so from my point of view this module is somehow correlated with swagger yes and swagger gives you all of those things like the console and HTML file and also ability to test your API during contract testing automatically so does this mmm acity form or rom form enable you to execute the contract tests by parked at the moment not I think we have pages we have a different rest Doc's trommel extension that's supporting Y amok so it's doing something different than spring cloud contract and image Y amok stops from your tests but yeah that's all at the moment so okay thank you yeah anyone else hi question is so as colleague said swagger enables you also to use this API testing live and do you know if there are any plans for Rommel and this view to support trying out the API without this open API without this API console you mean automatic yeah yeah and as I said like Rommel has this whole tool chain of supporting you to to ramp up mock service from from your Rommel files to to support your testing they have they have tools for that I didn't really look into that at too deeply but I know they have that but I also know that they are have having some some commercial offering regarding that so I'm not sure what's free and what's not but they might have some support at least I know they have a mock server that you can come up with and they might have more like each of these API descriptions like swear guards open API or API blueprint they all have like a whole lifecycle tool chain around their specifications thank you alright anyone else hello I wanted to ask for suggestions on how to document workflows within your API you know you have to call this get in this post and mmm such things yeah I think if you document processes or use cases to walk users through something common like plate creating a card adding products and placing an order that something that you probably would like to handwrite right so our plan is to to have this as handwritten documentation and these handwritten documentation could then point you to this API reference part where you have the dis bring Redsox documentation or something that you've generated out of your rama file and describe the resource in more detail so I think I can't think of a way to automate that right so that's it thank you very much and have a nice remaining day here [Applause]

Channel: Spring I/O

Views: 2,280

Rating: 5 out of 5

Keywords: springio18, Spring REST Docs, RAML

Id: VwKc34W96Cw

Length: 51min 10sec (3070 seconds)

Published: Tue Jul 03 2018