LINE DEVELOPER DAY 2017 C-4

2. Automatic API Document Generation 101
Nobuaki ITO _ Development Center 3

3. Swagger
Swagger is the world’s largest framework of API
developer tools for the OpenAPI Specification(OAS),
enabling development across the entire API lifecycle,
from design and documentation, to test and
deployment.

4. ざっくりいうと
OpenAPI Specification と
それをとりまくエコシステム

5. Swagger
Editor
Swagger
Codegen
Swagger
UI
コンポーネント

6. Swagger のエコシステム
OpenAPI Spec
CODE
DOCUMENT
Swagger Codegen
Swagger UISwagger Editor

7. つまり

8. API Spec First Development

9. - API Spec を Wiki で管理
- アプリは Spring (Boot) で開発
いっぽう現場では

10. ドキュメントと実装の乖離

11. そこで Swagger

12. API Spec First Development

14. そこで SpringFox

15. SpringFox
Spring のアプリケーションコードから
OpenAPI Spec File を生成する

16. Coding First Development

18. とはいえ

19. - Production Code に余計な依存が入るのでは？
- Production に余計な Entry Point が生えるのでは？
懸念

20. 心配ご無用

21. dependencies {
compileOnly('io.swagger:swagger-annotations:1.5.16')
testCompile('io.springfox:springfox-swagger2:2.7.0')
}
- Spec 記述部分は production 依存
- Spec 生成部分は test 依存

22. @TestConfiguration
@EnableSwagger2
class SwaggerDocketConfiguration { }
@Test
public void generateSwaggerOutput() throws Exception {
mockMvc.perform(get("/v2/api-docs")
.andDo(result -> {
try (val stream = new FileOutputStream(outputFile)) {
stream.write(result.getResponse()
.getContentAsByteArray());
}
});
}

23. 生成された OpenAPI Spec ファイル
{
"swagger": "2.0",
"info": {
"description": "API document of Hello World service",
"title": "API Specification of Hello World"
},
"tags": [
{
"name": "Arithmetic Calculation",
"description": "Provides several basic arithmetic function."
},
{
"name": "Greeting",
"description": "Provides greeting methods."
}
],
"paths": {
"/": {
"get": {
"tags": [
"Greeting"
],
"summary": "Top",
"description": "Get availability of the service.",
"operationId": "GreetingControllerTest_top",
......

24. OpenAPI Spec ファイルから markup 言語に変換
Swagger2Markup
Gradle / Maven plugin あり
AsciiDoc, Markdown をサポート

25. convertSwagger2markup {
dependsOn test
swaggerInput = ".../swagger.json"
outputDir file(".../generated")
config = [
'swagger2markup.pathsGroupedBy' : 'TAGS',
]
}
swagger2markup-gradle-plugin
Gradle task を提供するので他のタスクに依存可能

26. 生成された AsciiDoc ファイル
[[_paths]]
== Resources
[[_arithmetic_calculation_resource]]
=== Arithmetic Calculation
Provides several basic arithmetic function.
[[_arithmeticcontrollertest_add]]
==== Add
....
POST /arith/add
....
===== Description
Add two values.
...

27. convert2Swagger2markup のソース
asciidoctor-gradle-plugin
AsciiDoc ファイルから HTML や PDF を生成

28. HTML / PDF ができた

29. まとめ
Gradle タスクで一気通貫にできる
HTML
Source
Code
AsciiDoc
PDF
OpenAPI Spec
Swagger2MarkupSpringFox
AsciiDoctor

30. 完

31. ところで

32. Spring プロジェクトの
ドキュメント自動生成といえば

33. Spring REST Docs
テストコードからドキュメントを自動生成

34. mockMvc.perform(post("/notes").contentType(MediaType.APPLICATION_JSON)
.content("{}"))
.andExpect(status().isCreated())
.andDo(document("notes-create-example",
requestFields(
fieldWithPath("title")
.description("The title of the note"),
fieldWithPath("body")
.description("The body of the note"),
fieldWithPath("tags")
.description("An array of tag resource URIs"))));
Spring REST Docs example

36. でも

37. Spring REST Docs の出力

38. 魅力的

39. 心配ご無用

40. Swagger2Markup でもできます!

41. swagger2markup-spring-restdocs-ext

42. 要するに

43. Swagger2Markup
meets
Spring REST Docs

44. Spring REST Docs の設定を適切におこない
@TestConfiguration
public class RestDocsConfiguration {
@Bean
public RestDocumentationResultHandler resultHandler() {
return document("{ClassName}_{methodName}",
preprocessRequest(removeHeaders("Host", "Accept"),
prettyPrint()),
preprocessResponse(prettyPrint()));
}
}

45. Annotation でまとめる
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@AutoConfigureRestDocs(outputDir = "build/snippets",
uriHost = "example.com", uriPort = 80)
@Import(RestDocsConfiguration.class)
public @interface GenerateApiUsageExample {
}

46. @RunWith(SpringRunner.class)
@WebMvcTest(GreetingController.class)
@GenerateApiUsageExample
public class GreetingControllerTest {
@Test
public void greet() throws Exception {
mockMvc.perform(post("/greet")
.contentType(MediaType.APPLICATION_JSON)
.content(requestContent))
.andExpect(status().isOk())
.andExpect(content().json(expectedContent))
}
}
at test code

47. at controller code
@RestController
public class GreetingController {
@PostMapping(path = "/greet")
@ApiOperation(nickname = "GreetingControllerTest_greet")
public GreetingResponse greet(@RequestBody GreetingRequest request) {
// ...
}
}

48. Example Request / Response

50. Swagger UI

51. 静的ファイルをダウンロードして置くだけ

52. API Document in HTML
API Document in PDF
Swagger UI
API Document in Markup Language (AsciiDoc)
OpenAPI Spec file

53. - Git Repository に追加可能
- GitHub Pages に展開可能
すべて静的ファイルなので…
https://github.com/dayflower/example-api-doc-generation
https://dayflower.github.io/example-api-doc-generation/

54. おさらい
Gradle タスクで一気通貫にできる
REST
Docs
Snippets
HTML
Source
Code
AsciiDoc
PDF
GitHub
OpenAPI Spec
SpringFoxSwagger2Markup AsciiDoctor Git

55. ハマりどころ

56. クラス名が同じだと1つしかでない
package com.example.foo;
public class Baz {
// ...
}
package com.example.bar;
public class Baz {
// ...
}

57. クラス名が同じだと1つしかでない
package com.example.foo;
@ApiModel("foo.Baz")
public class Baz {
// ...
}
package com.example.bar;
@ApiModel("bar.Baz")
public class Baz {
// ...
}
⇒ Annotation 追加で対応可能

58. ⇒どうにもならない
@RestController
public class SampleController {
@PostMapping(value = "/create", params = "type=foo")
public Response createFoo(@RequestBody FooRequest) {
}
@PostMapping(value = "/create", params = "type=bar")
public Response createBar(@RequestBody BarRequest) {
}
}
パスが一緒だと1つしかでない

59. convert2Swagger2markup のソース
springfox-bean-validators
SpringFox meets Bean Validation (JSR-303)

60. springfox-bean-validators
@lombok.Value
public class Model {
@NotNull
@ApiModelProperty(required = true)
private String field;
}
@lombok.Value
public class Model {
@NotNull
private String field;
}

61. @ApiModelProperty を指定すると
@NotNull が消える
https://github.com/springfox/springfox/issues/1231
⇒どうにもならない
@lombok.Value
public class Model {
@NotNull
@ApiModelProperty(value="desc")
private String field;
}

62. 落穂ひろい

63. Coding First Development?

64. YAML / JSON を手書きするより
コードを書くほうが得意では?

65. 策定中 Spec の Entity を定義
Entity を入出力するダミーコードを書く

66. API Spec First Development 💖