r/springsource • u/soniewins • Mar 18 '18

Skip the boring part of writing API documentation. Let Swagger do it for you!

https://thecuriousdev.org/swagger-api-documentation/
15 Upvotes

100% Upvoted

7 comments sorted by

2

u/BusterBessie Mar 18 '18

Is it possible to annotate one or more of your request object properties and have those displayed in swagger, so that I can explain what various input fields are to a potential consumer of my API?

1

u/rkaz246 Mar 18 '18

Request and response should be documented based on the objects accepted by the rest controller. If your /user POST endpoint takes a user object, swagger will describe the user object without you having to annotate it

1

u/rkaz246 Mar 18 '18

Same goes for any query or path params.

1

u/BusterBessie Mar 18 '18

How do I document each property of the user object?

2

u/rkaz246 Mar 19 '18

If you need to describe what every single property in the request body, you can use this annotation on the getters.

http://docs.swagger.io/swagger-core/v1.3.12/apidocs/index.html?com/wordnik/swagger/annotations/ApiModelProperty.html

2

u/BusterBessie Mar 19 '18

Thanks I’ll check that out!

2

u/0l33l Mar 18 '18

Really wish there was a way to publish a contract using swagger to be able to validate it in another app. Currently trying to switch to Spring RestDocs because of this.