Documenting RESTful APIs
HTML-код
- Опубликовано: 12 сен 2024
- Recorded at SpringOne2GX 2015.
Track: Web / Javascript Track
Speaker: Andy Wilkinson
Slides: www.slideshare....
An API's documentation is a vital part of making it easy to understand and easy to use. RESTful APIs are no different. In this talk we'll look at what should be included in your RESTful API's documentation and, just as importantly, what should be omitted. Using real-word examples, both good and bad, we'll discuss how the documentation should be structured so that it's informative, succinct, and easy to read. Having identified what good documentation looks like, we'll discuss some of the tools that are available for documenting services built using Spring. In particular, we'll look at some of the problems and limitations of choosing a tool like Swagger and how some alternatives, including Spring REST Docs, avoid these shortcomings and help you to produce documentation that your users will love.
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`
Yes, Swagger has some limitation, especially the "annotation hell" is often annoying. But all in all it works quite well in the real world.
Нихера не видно. But sounds good tnx for your presentation.
How often do I google this video to convince people not using Swagger
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?
Recorded on VHS
Swagger is the best