swagger 2 spring boot generate yml file

Question

I'm new to swagger, contracts, and working on Spring boot (gradle) project where we are just starting with dealing with contracts. I've used grails, love how you can put field defs in the Domain and it gets inherited up through the stack.

A specific question and maybe a piggy backed splanation question too.

How can I generate basic stub of a YAML file from the standard Controller Class?

I understand I'm supposed to create a [Name]-v1-0.yml file in the directory controller\src\test\resources

I've implemented the swagger-ui.html in the project and a really cool interactive web page comes up showing request end points and stuffs. Using a class SwaggerConfig extends WebMvcConfigurerAdapter that works to publish the interfaces in ui json doc web page.

I believe the understanding is that the yml file in the test resources directory will be a fixed generation of the "contracts" and used in some sort of gradle test method to make sure the API signature and contract points have not changed, like a basic junit style test of the interface. (Yes/no?)

I'm lazy here thinking to myself, why am I hand hacking this stupid file? Can a yaml doc skeleton be generated for me pretty easy from the controller/model details?

For example on the page takes a YML file and does the ui friendly page: http://editor.swagger.io/#/

There's a really nice "uber" sample YAML file in that page, do I really need to write that, I already wrote the Controller, javadoc, annotated, all sorts of cool stuff that should be able to generate at least a pretty good starting stub of the yaml, (I blame you grails for not wanting to hack this!) that's before of course putting SpringFox annotations which do more cool stuffs and really going to town to drive more this testing contract assurance.

FYI: 'spring-boot-starter-web' 'spring-boot-starter-test' 'springfox-swagger-ui', version: '2.4.0'

Answer 1

I got it. Very simple, why didn't I see this anywhere. :)

Copy / paste the resource path in the browser:

http://localhost:8095/v2/api-docs?group=full-api

Select the generated content and copy to the clipboard.

Open the Swagger Editor in a browser:

http://editor.swagger.io

Select Paste JSON… from the File menu.

Paste the generated Swagger JSON content and click on Import.

Answer 2

There is a feature request to provide a yaml representation of the specs: https://github.com/springfox/springfox/issues/651

Besides the progress, it is not available yet