2:04 How RESTful is your API 2:29 REST maturity model 3:21 Level 1: Separate Resources 3:42 Level 2: HTTP verbs 4:12 Level 3: Hypermedia 5:43 How RESTful do you want it to be 9:47 Uniqueness 10:26 Concrete example of Hypermedia links 11:47 What should you document 12:00 cross-cutting concerns 13:49 resources 16:43 links 17:24 What shouldn't you document 17:29 URIs 19:42 What does it look like when you get it wrong 23:23 When you get it right 26:41 RESTful API documentation tools 26:58 Swagger 29:00 It doesn't support Hypermedia 29:24 It is URI centric 33:02 The writing experience is unpleasant 36:12 Swagger2Markup 40:07 *Spring REST Docs 40:48 RESTful API documentation design principle 1: Write as much as possible in a format that's designed for writing 41:25 RESTful API documentation design principle 2: Don't use the implementation to provide the documentation 42:49 RESTful API documentation design principle 3: Provide some guarantees that the documentation is accurate 43:30 Asciidoctor 44:27 Spring MVC Test 45:10 *Simple example: Restdocs with Spring MVC Test (MockMvc) 49:10 code for documenting links 50:49 produced snippets 51:53 Spring Rest Docs Demo 53:29 Use Spring REST Docs to document REST API 53:58 give it a go (试一下) with command `spring init`
Would be nice to have an refresh video... by the way once I added responseFields(fieldWithPath("_links").description... it no longer works... Do I have to document the notes, href, profile, href?
2:04 How RESTful is your API
2:29 REST maturity model
3:21 Level 1: Separate Resources
3:42 Level 2: HTTP verbs
4:12 Level 3: Hypermedia
5:43 How RESTful do you want it to be
9:47 Uniqueness
10:26 Concrete example of Hypermedia links
11:47 What should you document
12:00 cross-cutting concerns
13:49 resources
16:43 links
17:24 What shouldn't you document
17:29 URIs
19:42 What does it look like when you get it wrong
23:23 When you get it right
26:41 RESTful API documentation tools
26:58 Swagger
29:00 It doesn't support Hypermedia
29:24 It is URI centric
33:02 The writing experience is unpleasant
36:12 Swagger2Markup
40:07 *Spring REST Docs
40:48 RESTful API documentation design principle 1: Write as much as possible in a format that's designed for writing
41:25 RESTful API documentation design principle 2: Don't use the implementation to provide the documentation
42:49 RESTful API documentation design principle 3: Provide some guarantees that the documentation is accurate
43:30 Asciidoctor
44:27 Spring MVC Test
45:10 *Simple example: Restdocs with Spring MVC Test (MockMvc)
49:10 code for documenting links
50:49 produced snippets
51:53 Spring Rest Docs Demo
53:29 Use Spring REST Docs to document REST API
53:58 give it a go (试一下) with command `spring init`
How often do I google this video to convince people not using Swagger
Yes, Swagger has some limitation, especially the "annotation hell" is often annoying. But all in all it works quite well in the real world.
Would be nice to have an refresh video... by the way once I added responseFields(fieldWithPath("_links").description... it no longer works... Do I have to document the notes, href, profile, href?
Нихера не видно. But sounds good tnx for your presentation.
Recorded on VHS
Swagger is the best