Diese Präsentation wurde erfolgreich gemeldet.
Wir verwenden Ihre LinkedIn Profilangaben und Informationen zu Ihren Aktivitäten, um Anzeigen zu personalisieren und Ihnen relevantere Inhalte anzuzeigen. Sie können Ihre Anzeigeneinstellungen jederzeit ändern.
Introducing
Spring Auto REST Docs
Florian Benz
@flbenz
@spring_io
#springio17
DR REST DOCS
OR: HOW I LEARNED TO STOP WORRYING
AND LOVE DOCUMENTATION
@spring_io
#springio17
Florian Benz
Software Engineer
@flbenz
@spring_io
#springio17
Scalable Capital
• Europe’s fastest growing Digital Wealth Manager
• Authorized financial institute...
@spring_io
#springio17
Spring Auto REST Docs
Scalable Capital
founded
Dec 2014
Proof of concept
Jul 2015
First article
Nov...
@spring_io
#springio17
Spring Auto REST Docs
Open source
&
First release
Dec 2016
DZone article
Jan 2017
Two releases
with...
@spring_io
#springio17
Our Story
@spring_io
#springio17
Manual Documentation
DocumentationCode
@spring_io
#springio17
A single big document
@spring_io
#springio17
Specification-Driven
Documentation
DocumentationCode
Specification
@spring_io
#springio17
RAML Specification
/weather:
get:
queryParameters:
city:
description: Name of a city in the given c...
@spring_io
#springio17
Swagger / OpenAPI
@GetMapping("weatherParam")
@ApiOperation("weather")
@ApiImplicitParams({
@ApiImp...
@spring_io
#springio17
Swagger / OpenAPI
@spring_io
#springio17
Postman
@spring_io
#springio17
Test-Driven Documentation
DocumentationCode
Tests
@spring_io
#springio17
Spring REST Docs
Generated
snippets
Tests
Hand-written
documentation
Documentation
@spring_io
#springio17
Spring MVC Test
@Test
public void shouldReturnWeatherForBarcelona() throws Exception {
mockMvc.perf...
@spring_io
#springio17
Spring REST Docs
@Test
public void shouldReturnWeatherForBarcelona() throws Exception {
mockMvc.per...
@spring_io
#springio17
Generated snippet
|===
|Path|Type|Optional|Description
|country
|String
|false
|Country Code.
|city...
@spring_io
#springio17
AsciiDoc
[[resources-weather]]
= Weather for your city
`POST /weather`
Up-to-date temperature for t...
@spring_io
#springio17
Spring REST Docs
@spring_io
#springio17
Spring REST Docs
@spring_io
#springio17
Spring REST Docs
Controller
POJO
Response Entity
Jackson
HTTP response Documented
@spring_io
#springio17
Extending
Spring REST Docs
@spring_io
#springio17
Motivation
.andDo(document("weather",
requestFields(
fieldWithPath("country").description("Country ...
@spring_io
#springio17
Proof of concept
@spring_io
#springio17
Spring Auto REST Docs
Controller
POJO
Response Entity
Jackson
HTTP response
Javadoc
Introspection
@spring_io
#springio17
Spring REST Docs
@Test
public void shouldReturnWeatherForBarcelona() throws Exception {
mockMvc.per...
@spring_io
#springio17
Spring Auto REST Docs
@Test
public void shouldReturnWeatherForBarcelona() throws Exception {
mockMv...
@spring_io
#springio17
Javadoc
class WeatherRequest {
/**
* Country code.
*/
private String country;
/**
* City name.
*/
p...
@spring_io
#springio17
Constraints
class WeatherRequest {
/**
* Country code, e.g. ES, DE, US.
*/
@NotNull
@IsoCountryCode...
@spring_io
#springio17
Constraints
package.OneOf.description=Must be one of ${value}
package.IsoCountryCode.description=Mu...
@spring_io
#springio17
Constraints
class WeatherRequest {
/**
* Country code, e.g. ES, DE, US.
*/
@NotNull
@IsoCountryCode...
@spring_io
#springio17
Enums
class WeatherRequest {
/**
* Country code, e.g. ES, DE, US.
*/
@NotNull
private Country count...
@spring_io
#springio17
Original: hand-written
2.8. Weather
POST /weather
Up-to-date weather data for cities around the glo...
@spring_io
#springio17
Extension: Javadoc on method
/**
* Up-to-date weather data for cities around the globe.
*/
@PostMap...
@spring_io
#springio17
Original: Path Parameters
.andDo(document("weather",
pathParameters(
parameterWithName("country").d...
@spring_io
#springio17
Extension: Path Parameters
/**
* Up-to-date weather data for cities around the globe.
*
* @param co...
@spring_io
#springio17
Path Parameters
@spring_io
#springio17
Path Parameters
@spring_io
#springio17
Original: Query Parameters
.andDo(document("weather",
requestParameters(
parameterWithName("country...
@spring_io
#springio17
Extension: Query Parameters
/**
* Up-to-date weather data for cities around the globe.
*
* @param c...
@spring_io
#springio17
Query Parameters
@spring_io
#springio17
Query Parameters
@spring_io
#springio17
Section Snippet
[[resources-weather]]
=== Weather for your city
`POST /weather`
Up-to-date temperat...
@spring_io
#springio17
Authorization snippet
@spring_io
#springio17
Content Modifiers
[
1,
2,
3,
4,
5
]
[
1,
2,
3
]
array shortener
@spring_io
#springio17
Content Modifiers
%PDF-1.5
%����
12 0 obj
<<
/Length 3654
/Filter /FlateDecode
>>
<binary>
binary r...
@spring_io
#springio17
Benefits
Less to write
Code review Maintainability
Happier developers
DRY
Accurate
@spring_io
#springio17
Sounds good!
Issues?
@spring_io
#springio17
Issues
@spring_io
#springio17
Issues
@spring_io
#springio17
Issues
@spring_io
#springio17
It’s an extension
Authorization snippet
Javadoc/introspection snippets
Content modifiers
@spring_io
#springio17
Spring Auto REST Docs
at Scalable Capital
@spring_io
#springio17
Spring Auto REST Docs
at Scalable Capital
@spring_io
#springio17
Thank you
@spring_io
#springio17
Q&A
@flbenz
Nächste SlideShare
Wird geladen in …5
×

Introducing Spring Auto REST Docs - Spring IO 2017

1.983 Aufrufe

Veröffentlicht am

This talk introduces Spring Auto REST Docs, an extension to Spring REST Docs that helps you write less and get more. We have been using and evolving our Spring REST Docs extension for over 1.5 years and recently open sourced it: https://github.com/ScaCap/spring-auto-restdocs Spring Auto REST Docs uses tests, introspection and Javadoc to automatically document request and response parameters. We will look at how much work this saved and how it increased the quality of our documentation. Sprint Auto REST Docs proposes a tight coupling of code and documentation. This way we make it easy to add documentation in the first place, and to keep it up to date as your platform evolves. During the presentation, we give instructions on how to use the extension and discuss pros and cons of the proposed approach. We will present our own system as a real-life implementation and highlight the benefits of reusing tests, bean validation and Javadoc together with the freedom of AsciiDoc to generate documentation.

For further reading: https://dzone.com/articles/introducing-spring-auto-rest-docs
Project documentation: https://scacap.github.io/spring-auto-restdocs/
Project: https://github.com/ScaCap/spring-auto-restdocs

Veröffentlicht in: Software
  • After many failed attempts, I almost packed in my GCSE maths altogether. But fortunately I didn't, thanks to Jeevan's guide! When I read it, I found out exactly where I was going wrong all this time! I followed his approach and achieved 90% in my next sitting. I was shocked and I thought it was a total fluke so I put his strategy to the test again. This time, I got 100%! Fantastic! If only I came across Jeevan's strategy sooner. Learn more.. ♥♥♥ http://t.cn/AirrSv7D
       Antworten 
    Sind Sie sicher, dass Sie …  Ja  Nein
    Ihre Nachricht erscheint hier
  • Before coming across your guide, I wasn't highly motivated to study nor confident that I would achieve the best grades in my GCSEs. However, after reading about your success and what your program has done for others, it inspired me to do better and aim for the best results. At the end of the day, there is no reason why anyone cannot achieve the best grades in their studies... Your maths revision guide/strategy is fantastic! You have really opened my eyes as to where I've been going wrong all this time and what I should focus on, going forward. I've also applied your methods to other subjects too such as Science and seen a vast improvement in terms of revision and progress. I cannot thank you enough for sharing your strategy! I am very confident that, providing I follow your plan, I will excel in my final GCSE exams next year and most importantly, make my family proud! :)➤➤ http://ishbv.com/jeevan91/pdf
       Antworten 
    Sind Sie sicher, dass Sie …  Ja  Nein
    Ihre Nachricht erscheint hier
  • Thanks to all your information and revision techniques, I got an A* in my Maths GCSE exam... I was predicted a C but I wanted to go that extra mile and make my parents proud. I struggled with Algebra but using your resources, I found it easy and conquered the challenge. Thank you so much! ◆◆◆ http://t.cn/AirrSv7D
       Antworten 
    Sind Sie sicher, dass Sie …  Ja  Nein
    Ihre Nachricht erscheint hier
  • DOWNLOAD THAT BOOKS INTO AVAILABLE FORMAT (2019 Update) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { http://bit.ly/2m6jJ5M } ......................................................................................................................... Download Full EPUB Ebook here { http://bit.ly/2m6jJ5M } ......................................................................................................................... Download Full doc Ebook here { http://bit.ly/2m6jJ5M } ......................................................................................................................... Download PDF EBOOK here { http://bit.ly/2m6jJ5M } ......................................................................................................................... Download EPUB Ebook here { http://bit.ly/2m6jJ5M } ......................................................................................................................... Download doc Ebook here { http://bit.ly/2m6jJ5M } ......................................................................................................................... ......................................................................................................................... ................................................................................................................................... eBook is an electronic version of a traditional print book that can be read by using a personal computer or by using an eBook reader. (An eBook reader can be a software application for use on a computer such as Microsoft's free Reader application, or a book-sized computer that is used solely as a reading device such as Nuvomedia's Rocket eBook.) Users can purchase an eBook on diskette or CD, but the most popular method of getting an eBook is to purchase a downloadable file of the eBook (or other reading material) from a Web site (such as Barnes and Noble) to be read from the user's computer or reading device. Generally, an eBook can be downloaded in five minutes or less ......................................................................................................................... .............. Browse by Genre Available eBooks .............................................................................................................................. Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, ......................................................................................................................... ......................................................................................................................... .....BEST SELLER FOR EBOOK RECOMMEND............................................................. ......................................................................................................................... Blowout: Corrupted Democracy, Rogue State Russia, and the Richest, Most Destructive Industry on Earth,-- The Ride of a Lifetime: Lessons Learned from 15 Years as CEO of the Walt Disney Company,-- Call Sign Chaos: Learning to Lead,-- StrengthsFinder 2.0,-- Stillness Is the Key,-- She Said: Breaking the Sexual Harassment Story That Helped Ignite a Movement,-- Atomic Habits: An Easy &amp; Proven Way to Build Good Habits &amp; Break Bad Ones,-- Everything Is Figureoutable,-- What It Takes: Lessons in the Pursuit of Excellence,-- Rich Dad Poor Dad: What the Rich Teach Their Kids About Money That the Poor and Middle Class Do Not!,-- The Total Money Makeover: Classic Edition: A Proven Plan for Financial Fitness,-- Shut Up and Listen!: Hard Business Truths that Will Help You Succeed, ......................................................................................................................... .........................................................................................................................
       Antworten 
    Sind Sie sicher, dass Sie …  Ja  Nein
    Ihre Nachricht erscheint hier

Introducing Spring Auto REST Docs - Spring IO 2017

  1. 1. Introducing Spring Auto REST Docs Florian Benz @flbenz
  2. 2. @spring_io #springio17 DR REST DOCS OR: HOW I LEARNED TO STOP WORRYING AND LOVE DOCUMENTATION
  3. 3. @spring_io #springio17 Florian Benz Software Engineer @flbenz
  4. 4. @spring_io #springio17 Scalable Capital • Europe’s fastest growing Digital Wealth Manager • Authorized financial institute in Germany and the UK • From scratch with Spring Boot • Joined effort with Juraj Misur @juraj_misur
  5. 5. @spring_io #springio17 Spring Auto REST Docs Scalable Capital founded Dec 2014 Proof of concept Jul 2015 First article Nov 2015
  6. 6. @spring_io #springio17 Spring Auto REST Docs Open source & First release Dec 2016 DZone article Jan 2017 Two releases with fixes and features Feb & Mar 2017
  7. 7. @spring_io #springio17 Our Story
  8. 8. @spring_io #springio17 Manual Documentation DocumentationCode
  9. 9. @spring_io #springio17 A single big document
  10. 10. @spring_io #springio17 Specification-Driven Documentation DocumentationCode Specification
  11. 11. @spring_io #springio17 RAML Specification /weather: get: queryParameters: city: description: Name of a city in the given country. responses: 200: body: application/json: schema: | { "$schema": "http://json-schema.org/schema", "type": "object", "description": "Weather information", "properties": { "temperature": { "type": "number" } } }
  12. 12. @spring_io #springio17 Swagger / OpenAPI @GetMapping("weatherParam") @ApiOperation("weather") @ApiImplicitParams({ @ApiImplicitParam(name = "country", value = "Country code", required = true, dataType = "string", paramType = "query"), @ApiImplicitParam(name = "city", value = "City", required = true, dataType = "string", paramType = "query") }) @ApiResponses({ @ApiResponse(code = 200, message = "Success", response = WeatherResponse.class) }) public WeatherResponse weatherParam(@RequestParam @IsoCountryCode String country, @RequestParam String city) { return new WeatherResponse(20); }
  13. 13. @spring_io #springio17 Swagger / OpenAPI
  14. 14. @spring_io #springio17 Postman
  15. 15. @spring_io #springio17 Test-Driven Documentation DocumentationCode Tests
  16. 16. @spring_io #springio17 Spring REST Docs Generated snippets Tests Hand-written documentation Documentation
  17. 17. @spring_io #springio17 Spring MVC Test @Test public void shouldReturnWeatherForBarcelona() throws Exception { mockMvc.perform( post("/weather") .contentType(MediaType.APPLICATION_JSON) .content("{"country": "ES", "city": "Barcelona"}") ) .andExpect(status().isOk()) .andExpect(jsonPath("$.temperature", is(20))); }
  18. 18. @spring_io #springio17 Spring REST Docs @Test public void shouldReturnWeatherForBarcelona() throws Exception { mockMvc.perform( post("/weather") .contentType(MediaType.APPLICATION_JSON) .content("{"country": "ES", "city": "Barcelona"}") ) .andExpect(status().isOk()) .andExpect(jsonPath("$.temperature", is(20))); .andDo(document("weather", requestFields( fieldWithPath("country").description("Country code"), fieldWithPath("city").description("City name")))); }
  19. 19. @spring_io #springio17 Generated snippet |=== |Path|Type|Optional|Description |country |String |false |Country Code. |city |false |true |City name. |===
  20. 20. @spring_io #springio17 AsciiDoc [[resources-weather]] = Weather for your city `POST /weather` Up-to-date temperature for the given city == Response structure include::{snippets}/weather/response-fields.adoc[] == Example request/response include::{snippets}/weather/curl-request.adoc[] include::{snippets}/weather/http-response.adoc[]
  21. 21. @spring_io #springio17 Spring REST Docs
  22. 22. @spring_io #springio17 Spring REST Docs
  23. 23. @spring_io #springio17 Spring REST Docs Controller POJO Response Entity Jackson HTTP response Documented
  24. 24. @spring_io #springio17 Extending Spring REST Docs
  25. 25. @spring_io #springio17 Motivation .andDo(document("weather", requestFields( fieldWithPath("country").description("Country code"), fieldWithPath("city").description("Name of a city")))); We are lazy
  26. 26. @spring_io #springio17 Proof of concept
  27. 27. @spring_io #springio17 Spring Auto REST Docs Controller POJO Response Entity Jackson HTTP response Javadoc Introspection
  28. 28. @spring_io #springio17 Spring REST Docs @Test public void shouldReturnWeatherForBarcelona() throws Exception { mockMvc.perform( post("/weather") .contentType(MediaType.APPLICATION_JSON) .content("{"country": "ES", "city": "Barcelona"}") ) .andExpect(status().isOk()) .andExpect(jsonPath("$.temperature", is(20))); .andDo(document("weather", requestFields( fieldWithPath("country").optional().description("Country code"), fieldWithPath("city").optional().description("City name")))); }
  29. 29. @spring_io #springio17 Spring Auto REST Docs @Test public void shouldReturnWeatherForBarcelona() throws Exception { mockMvc.perform( post("/weather") .contentType(MediaType.APPLICATION_JSON) .content("{"country": "ES", "city": "Barcelona"}") ) .andExpect(status().isOk()) .andExpect(jsonPath("$.temperature", is(20))); .andDo(document("weather")); }
  30. 30. @spring_io #springio17 Javadoc class WeatherRequest { /** * Country code. */ private String country; /** * City name. */ private String city; } Path Type Optional Description country String true Country code. city String true City name.
  31. 31. @spring_io #springio17 Constraints class WeatherRequest { /** * Country code, e.g. ES, DE, US. */ @NotNull @IsoCountryCode private String country; /** * City name. */ @NotBlank private String city; } Path Type Optional Description country String false Country code. Must be an ISO country code. city String false City name.
  32. 32. @spring_io #springio17 Constraints package.OneOf.description=Must be one of ${value} package.IsoCountryCode.description=Must be an ISO country code ConstraintDesciptions.properties
  33. 33. @spring_io #springio17 Constraints class WeatherRequest { /** * Country code, e.g. ES, DE, US. */ @NotNull @IsoCountryCode(groups = Iso.class) @CountryName(groups = Plain.class) private String country; } Path Type Optional Description country String false Country code. ISO: Must be an ISO country code. Plain: Must be a country name.
  34. 34. @spring_io #springio17 Enums class WeatherRequest { /** * Country code, e.g. ES, DE, US. */ @NotNull private Country country; /** * City name. */ @NotBlank private String city; } Path Type Optional Description country String false Country code. Must be one of [DE, ES, FR, PT, US]. city String false City name.
  35. 35. @spring_io #springio17 Original: hand-written 2.8. Weather POST /weather Up-to-date weather data for cities around the globe. [[resources-weather]] = Weather for your city `POST /weather` Up-to-date temperature for the given city
  36. 36. @spring_io #springio17 Extension: Javadoc on method /** * Up-to-date weather data for cities around the globe. */ @PostMapping("weather") public WeatherResponse weather( @RequestBody @Valid WeatherRequest weatherRequest) { return new WeatherResponse(20); } 2.8. Weather POST /weather Up-to-date weather data for cities around the globe.
  37. 37. @spring_io #springio17 Original: Path Parameters .andDo(document("weather", pathParameters( parameterWithName("country").description("Country code"), parameterWithName("city").description("City name"))));
  38. 38. @spring_io #springio17 Extension: Path Parameters /** * Up-to-date weather data for cities around the globe. * * @param country Country code. * @param city City name. */ @GetMapping("weather/{country}/{city}") public WeatherResponse weatherPath( @PathVariable @IsoCountryCode String country, @PathVariable String city) { return new WeatherResponse(20); }
  39. 39. @spring_io #springio17 Path Parameters
  40. 40. @spring_io #springio17 Path Parameters
  41. 41. @spring_io #springio17 Original: Query Parameters .andDo(document("weather", requestParameters( parameterWithName("country").description("Country code"), parameterWithName("city").description("City name"))));
  42. 42. @spring_io #springio17 Extension: Query Parameters /** * Up-to-date weather data for cities around the globe. * * @param country Country code. * @param city City name. */ @GetMapping("weatherParam") public WeatherResponse weatherParam( @RequestParam @IsoCountryCode String country, @RequestParam String city) { return new WeatherResponse(20); }
  43. 43. @spring_io #springio17 Query Parameters
  44. 44. @spring_io #springio17 Query Parameters
  45. 45. @spring_io #springio17 Section Snippet [[resources-weather]] === Weather for your city `POST /weather` Up-to-date temperature for the given city ===== Request structure include::{snippets}/weather/request-fields.adoc[] ===== Response structure include::{snippets}/weather/response-fields.adoc[] ===== Example request/response include::{snippets}/weather/curl-request.adoc[] include::{snippets}/weather/http-response.adoc[] include::{snippets}/weather/section.adoc[] Documentation path Spring MVC Controller Javadoc Method name
  46. 46. @spring_io #springio17 Authorization snippet
  47. 47. @spring_io #springio17 Content Modifiers [ 1, 2, 3, 4, 5 ] [ 1, 2, 3 ] array shortener
  48. 48. @spring_io #springio17 Content Modifiers %PDF-1.5 %���� 12 0 obj << /Length 3654 /Filter /FlateDecode >> <binary> binary replacement
  49. 49. @spring_io #springio17 Benefits Less to write Code review Maintainability Happier developers DRY Accurate
  50. 50. @spring_io #springio17 Sounds good! Issues?
  51. 51. @spring_io #springio17 Issues
  52. 52. @spring_io #springio17 Issues
  53. 53. @spring_io #springio17 Issues
  54. 54. @spring_io #springio17 It’s an extension Authorization snippet Javadoc/introspection snippets Content modifiers
  55. 55. @spring_io #springio17 Spring Auto REST Docs at Scalable Capital
  56. 56. @spring_io #springio17 Spring Auto REST Docs at Scalable Capital
  57. 57. @spring_io #springio17 Thank you
  58. 58. @spring_io #springio17 Q&A @flbenz

×