Submit Search
Upload
こんなに使える!今どきのAPIドキュメンテーションツール
•
142 likes
•
26,103 views
dcubeio
Follow
http://d-cube.connpass.com/event/43057/ にて発表した内容です
Read less
Read more
Engineering
Report
Share
Report
Share
1 of 52
Download now
Download to read offline
Recommended
KeycloakでAPI認可に入門する
KeycloakでAPI認可に入門する
Hitachi, Ltd. OSS Solution Center.
REST API のコツ
REST API のコツ
pospome
Redisの特徴と活用方法について
Redisの特徴と活用方法について
Yuji Otani
Keycloak拡張入門
Keycloak拡張入門
Hiroyuki Wada
Dockerからcontainerdへの移行
Dockerからcontainerdへの移行
Akihiro Suda
マイクロにしすぎた結果がこれだよ!
マイクロにしすぎた結果がこれだよ!
mosa siru
Spring Boot の Web アプリケーションを Docker に載せて AWS ECS で動かしている話
Spring Boot の Web アプリケーションを Docker に載せて AWS ECS で動かしている話
JustSystems Corporation
Azure API Management 俺的マニュアル
Azure API Management 俺的マニュアル
貴志 上坂
Recommended
KeycloakでAPI認可に入門する
KeycloakでAPI認可に入門する
Hitachi, Ltd. OSS Solution Center.
REST API のコツ
REST API のコツ
pospome
Redisの特徴と活用方法について
Redisの特徴と活用方法について
Yuji Otani
Keycloak拡張入門
Keycloak拡張入門
Hiroyuki Wada
Dockerからcontainerdへの移行
Dockerからcontainerdへの移行
Akihiro Suda
マイクロにしすぎた結果がこれだよ!
マイクロにしすぎた結果がこれだよ!
mosa siru
Spring Boot の Web アプリケーションを Docker に載せて AWS ECS で動かしている話
Spring Boot の Web アプリケーションを Docker に載せて AWS ECS で動かしている話
JustSystems Corporation
Azure API Management 俺的マニュアル
Azure API Management 俺的マニュアル
貴志 上坂
Java ORマッパー選定のポイント #jsug
Java ORマッパー選定のポイント #jsug
Masatoshi Tada
AWSのログ管理ベストプラクティス
AWSのログ管理ベストプラクティス
Akihiro Kuwano
AWSとオンプレミスを繋ぐときに知っておきたいルーティングの基礎知識(CCSI監修!)
AWSとオンプレミスを繋ぐときに知っておきたいルーティングの基礎知識(CCSI監修!)
Trainocate Japan, Ltd.
Keycloak入門
Keycloak入門
Hiroyuki Wada
Kongの概要と導入事例
Kongの概要と導入事例
briscola-tokyo
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
Takuto Wada
SPAセキュリティ入門~PHP Conference Japan 2021
SPAセキュリティ入門~PHP Conference Japan 2021
Hiroshi Tokumaru
例外設計における大罪
例外設計における大罪
Takuto Wada
マイクロサービス時代の認証と認可 - AWS Dev Day Tokyo 2018 #AWSDevDay
マイクロサービス時代の認証と認可 - AWS Dev Day Tokyo 2018 #AWSDevDay
都元ダイスケ Miyamoto
Infrastructure as Code (IaC) 談義 2022
Infrastructure as Code (IaC) 談義 2022
Amazon Web Services Japan
怖くないSpring Bootのオートコンフィグレーション
怖くないSpring Bootのオートコンフィグレーション
土岐 孝平
Dockerイメージの理解とコンテナのライフサイクル
Dockerイメージの理解とコンテナのライフサイクル
Masahito Zembutsu
エンジニアの個人ブランディングと技術組織
エンジニアの個人ブランディングと技術組織
Takafumi ONAKA
マイクロサービスバックエンドAPIのためのRESTとgRPC
マイクロサービスバックエンドAPIのためのRESTとgRPC
disc99_
なぜOpenID Connectが必要となったのか、その歴史的背景
なぜOpenID Connectが必要となったのか、その歴史的背景
Tatsuo Kudo
マイクロサービスにおけるテスト自動化 with Karate
マイクロサービスにおけるテスト自動化 with Karate
Takanori Suzuki
モノリスからマイクロサービスへの移行 ~ストラングラーパターンの検証~(Spring Fest 2020講演資料)
モノリスからマイクロサービスへの移行 ~ストラングラーパターンの検証~(Spring Fest 2020講演資料)
NTT DATA Technology & Innovation
基礎からのOAuth 2.0とSpring Security 5.1による実装
基礎からのOAuth 2.0とSpring Security 5.1による実装
Masatoshi Tada
Kinesis + Elasticsearchでつくるさいきょうのログ分析基盤
Kinesis + Elasticsearchでつくるさいきょうのログ分析基盤
Amazon Web Services Japan
シリコンバレーの「何が」凄いのか
シリコンバレーの「何が」凄いのか
Atsushi Nakada
ドキュメントを作りたくなってしまう魔法のツールSphinx
ドキュメントを作りたくなってしまう魔法のツールSphinx
Takayuki Shimizukawa
技術者が知るべき Gröbner 基底
技術者が知るべき Gröbner 基底
Hiromi Ishii
More Related Content
What's hot
Java ORマッパー選定のポイント #jsug
Java ORマッパー選定のポイント #jsug
Masatoshi Tada
AWSのログ管理ベストプラクティス
AWSのログ管理ベストプラクティス
Akihiro Kuwano
AWSとオンプレミスを繋ぐときに知っておきたいルーティングの基礎知識(CCSI監修!)
AWSとオンプレミスを繋ぐときに知っておきたいルーティングの基礎知識(CCSI監修!)
Trainocate Japan, Ltd.
Keycloak入門
Keycloak入門
Hiroyuki Wada
Kongの概要と導入事例
Kongの概要と導入事例
briscola-tokyo
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
Takuto Wada
SPAセキュリティ入門~PHP Conference Japan 2021
SPAセキュリティ入門~PHP Conference Japan 2021
Hiroshi Tokumaru
例外設計における大罪
例外設計における大罪
Takuto Wada
マイクロサービス時代の認証と認可 - AWS Dev Day Tokyo 2018 #AWSDevDay
マイクロサービス時代の認証と認可 - AWS Dev Day Tokyo 2018 #AWSDevDay
都元ダイスケ Miyamoto
Infrastructure as Code (IaC) 談義 2022
Infrastructure as Code (IaC) 談義 2022
Amazon Web Services Japan
怖くないSpring Bootのオートコンフィグレーション
怖くないSpring Bootのオートコンフィグレーション
土岐 孝平
Dockerイメージの理解とコンテナのライフサイクル
Dockerイメージの理解とコンテナのライフサイクル
Masahito Zembutsu
エンジニアの個人ブランディングと技術組織
エンジニアの個人ブランディングと技術組織
Takafumi ONAKA
マイクロサービスバックエンドAPIのためのRESTとgRPC
マイクロサービスバックエンドAPIのためのRESTとgRPC
disc99_
なぜOpenID Connectが必要となったのか、その歴史的背景
なぜOpenID Connectが必要となったのか、その歴史的背景
Tatsuo Kudo
マイクロサービスにおけるテスト自動化 with Karate
マイクロサービスにおけるテスト自動化 with Karate
Takanori Suzuki
モノリスからマイクロサービスへの移行 ~ストラングラーパターンの検証~(Spring Fest 2020講演資料)
モノリスからマイクロサービスへの移行 ~ストラングラーパターンの検証~(Spring Fest 2020講演資料)
NTT DATA Technology & Innovation
基礎からのOAuth 2.0とSpring Security 5.1による実装
基礎からのOAuth 2.0とSpring Security 5.1による実装
Masatoshi Tada
Kinesis + Elasticsearchでつくるさいきょうのログ分析基盤
Kinesis + Elasticsearchでつくるさいきょうのログ分析基盤
Amazon Web Services Japan
シリコンバレーの「何が」凄いのか
シリコンバレーの「何が」凄いのか
Atsushi Nakada
What's hot
(20)
Java ORマッパー選定のポイント #jsug
Java ORマッパー選定のポイント #jsug
AWSのログ管理ベストプラクティス
AWSのログ管理ベストプラクティス
AWSとオンプレミスを繋ぐときに知っておきたいルーティングの基礎知識(CCSI監修!)
AWSとオンプレミスを繋ぐときに知っておきたいルーティングの基礎知識(CCSI監修!)
Keycloak入門
Keycloak入門
Kongの概要と導入事例
Kongの概要と導入事例
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
SPAセキュリティ入門~PHP Conference Japan 2021
SPAセキュリティ入門~PHP Conference Japan 2021
例外設計における大罪
例外設計における大罪
マイクロサービス時代の認証と認可 - AWS Dev Day Tokyo 2018 #AWSDevDay
マイクロサービス時代の認証と認可 - AWS Dev Day Tokyo 2018 #AWSDevDay
Infrastructure as Code (IaC) 談義 2022
Infrastructure as Code (IaC) 談義 2022
怖くないSpring Bootのオートコンフィグレーション
怖くないSpring Bootのオートコンフィグレーション
Dockerイメージの理解とコンテナのライフサイクル
Dockerイメージの理解とコンテナのライフサイクル
エンジニアの個人ブランディングと技術組織
エンジニアの個人ブランディングと技術組織
マイクロサービスバックエンドAPIのためのRESTとgRPC
マイクロサービスバックエンドAPIのためのRESTとgRPC
なぜOpenID Connectが必要となったのか、その歴史的背景
なぜOpenID Connectが必要となったのか、その歴史的背景
マイクロサービスにおけるテスト自動化 with Karate
マイクロサービスにおけるテスト自動化 with Karate
モノリスからマイクロサービスへの移行 ~ストラングラーパターンの検証~(Spring Fest 2020講演資料)
モノリスからマイクロサービスへの移行 ~ストラングラーパターンの検証~(Spring Fest 2020講演資料)
基礎からのOAuth 2.0とSpring Security 5.1による実装
基礎からのOAuth 2.0とSpring Security 5.1による実装
Kinesis + Elasticsearchでつくるさいきょうのログ分析基盤
Kinesis + Elasticsearchでつくるさいきょうのログ分析基盤
シリコンバレーの「何が」凄いのか
シリコンバレーの「何が」凄いのか
Viewers also liked
ドキュメントを作りたくなってしまう魔法のツールSphinx
ドキュメントを作りたくなってしまう魔法のツールSphinx
Takayuki Shimizukawa
技術者が知るべき Gröbner 基底
技術者が知るべき Gröbner 基底
Hiromi Ishii
とある制作会社の目次索引作成技法
とある制作会社の目次索引作成技法
Kenshi Muto
書籍向け汎用マークアップのあり方―Re:VIEWの開発を通して
書籍向け汎用マークアップのあり方―Re:VIEWの開発を通して
Kenshi Muto
今だからこそ知りたい Docker Compose/Swarm 入門
今だからこそ知りたい Docker Compose/Swarm 入門
Masahito Zembutsu
脱RESTful API設計の提案
脱RESTful API設計の提案
樽八 仲川
Docker Swarm入門
Docker Swarm入門
Masahito Zembutsu
書籍制作でReVIEWを使う実践ワークフロー
書籍制作でReVIEWを使う実践ワークフロー
Masahiro Hidaka
Swaggerでのapi開発よもやま話
Swaggerでのapi開発よもやま話
KEISUKE KONISHI
失敗事例で学ぶ負荷試験
失敗事例で学ぶ負荷試験
樽八 仲川
Viewers also liked
(10)
ドキュメントを作りたくなってしまう魔法のツールSphinx
ドキュメントを作りたくなってしまう魔法のツールSphinx
技術者が知るべき Gröbner 基底
技術者が知るべき Gröbner 基底
とある制作会社の目次索引作成技法
とある制作会社の目次索引作成技法
書籍向け汎用マークアップのあり方―Re:VIEWの開発を通して
書籍向け汎用マークアップのあり方―Re:VIEWの開発を通して
今だからこそ知りたい Docker Compose/Swarm 入門
今だからこそ知りたい Docker Compose/Swarm 入門
脱RESTful API設計の提案
脱RESTful API設計の提案
Docker Swarm入門
Docker Swarm入門
書籍制作でReVIEWを使う実践ワークフロー
書籍制作でReVIEWを使う実践ワークフロー
Swaggerでのapi開発よもやま話
Swaggerでのapi開発よもやま話
失敗事例で学ぶ負荷試験
失敗事例で学ぶ負荷試験
Similar to こんなに使える!今どきのAPIドキュメンテーションツール
IDEを目指す開発者コンソール
IDEを目指す開発者コンソール
minoaw
『 イドラ ファンタシースターサーガ 』を支える GCP | Google Cloud INSIDE Games & Apps
『 イドラ ファンタシースターサーガ 』を支える GCP | Google Cloud INSIDE Games & Apps
Google Cloud Platform - Japan
5 年続く 「はてなブックマーク」 アプリを継続開発する技術
5 年続く 「はてなブックマーク」 アプリを継続開発する技術
Yu Nobuoka
Swagger jjug ccc 2018 spring
Swagger jjug ccc 2018 spring
kounan13
Goji とレイヤ化アーキテクチャ
Goji とレイヤ化アーキテクチャ
Shiroyagi Corporation
HTML5 アプリ開発
HTML5 アプリ開発
tomo_masakura
.NET Core diagnostics tips
.NET Core diagnostics tips
Yusuke Fujiwara
Start-padrino
Start-padrino
Uchio Kondo
Djangoのススメ
Djangoのススメ
Alisue Lambda
Angular 4がやってくる!? 新機能ダイジェスト
Angular 4がやってくる!? 新機能ダイジェスト
Masahiko Asai
コンパイラ指向ReVIEW
コンパイラ指向ReVIEW
Masahiro Wakame
Scalaでのプログラム開発
Scalaでのプログラム開発
Kota Mizushima
ゲームのインフラをAwsで実戦tips全て見せます
ゲームのインフラをAwsで実戦tips全て見せます
infinite_loop
Azure Function GAした!Visual Studio Tools for Azure Functions もプレビューだ!
Azure Function GAした!Visual Studio Tools for Azure Functions もプレビューだ!
Yasuaki Matsuda
REST API、gRPC、GraphQL 触ってみた【2023年12月開催勉強会資料】
REST API、gRPC、GraphQL 触ってみた【2023年12月開催勉強会資料】
洵貴 佐川
Pentaho ETL@DevLOVE関西
Pentaho ETL@DevLOVE関西
Hirokazu Tokuno
サーバサイドエンジニアが 1年間まじめにSPAやってみた
サーバサイドエンジニアが 1年間まじめにSPAやってみた
Itaru Kitagawa
SendGridにおけるStopLightを 活用したAPI管理
SendGridにおけるStopLightを 活用したAPI管理
Wataru Sato
Fluentd1.2 & Fluent Bit
Fluentd1.2 & Fluent Bit
Seiya Mizuno
マイクロサービスのためのフレームワークGoaのご紹介
マイクロサービスのためのフレームワークGoaのご紹介
Kazuaki Shibue
Similar to こんなに使える!今どきのAPIドキュメンテーションツール
(20)
IDEを目指す開発者コンソール
IDEを目指す開発者コンソール
『 イドラ ファンタシースターサーガ 』を支える GCP | Google Cloud INSIDE Games & Apps
『 イドラ ファンタシースターサーガ 』を支える GCP | Google Cloud INSIDE Games & Apps
5 年続く 「はてなブックマーク」 アプリを継続開発する技術
5 年続く 「はてなブックマーク」 アプリを継続開発する技術
Swagger jjug ccc 2018 spring
Swagger jjug ccc 2018 spring
Goji とレイヤ化アーキテクチャ
Goji とレイヤ化アーキテクチャ
HTML5 アプリ開発
HTML5 アプリ開発
.NET Core diagnostics tips
.NET Core diagnostics tips
Start-padrino
Start-padrino
Djangoのススメ
Djangoのススメ
Angular 4がやってくる!? 新機能ダイジェスト
Angular 4がやってくる!? 新機能ダイジェスト
コンパイラ指向ReVIEW
コンパイラ指向ReVIEW
Scalaでのプログラム開発
Scalaでのプログラム開発
ゲームのインフラをAwsで実戦tips全て見せます
ゲームのインフラをAwsで実戦tips全て見せます
Azure Function GAした!Visual Studio Tools for Azure Functions もプレビューだ!
Azure Function GAした!Visual Studio Tools for Azure Functions もプレビューだ!
REST API、gRPC、GraphQL 触ってみた【2023年12月開催勉強会資料】
REST API、gRPC、GraphQL 触ってみた【2023年12月開催勉強会資料】
Pentaho ETL@DevLOVE関西
Pentaho ETL@DevLOVE関西
サーバサイドエンジニアが 1年間まじめにSPAやってみた
サーバサイドエンジニアが 1年間まじめにSPAやってみた
SendGridにおけるStopLightを 活用したAPI管理
SendGridにおけるStopLightを 活用したAPI管理
Fluentd1.2 & Fluent Bit
Fluentd1.2 & Fluent Bit
マイクロサービスのためのフレームワークGoaのご紹介
マイクロサービスのためのフレームワークGoaのご紹介
More from dcubeio
AWS Summit Tokyo 2019登壇資料「DevOpsの劇的改善!古いアーキテクチャから王道のマネージドサービスを活用しフルリプレイス! 」
AWS Summit Tokyo 2019登壇資料「DevOpsの劇的改善!古いアーキテクチャから王道のマネージドサービスを活用しフルリプレイス! 」
dcubeio
20170329 D3 DBAが夜間メンテをしなくなった日 発表資料
20170329 D3 DBAが夜間メンテをしなくなった日 発表資料
dcubeio
ビットコインとブロックチェーンを初めからていねいに(超基礎編)
ビットコインとブロックチェーンを初めからていねいに(超基礎編)
dcubeio
20171206 d3 health_tech発表資料
20171206 d3 health_tech発表資料
dcubeio
Go初心者がGoでコマンドラインツールの作成に挑戦した話
Go初心者がGoでコマンドラインツールの作成に挑戦した話
dcubeio
初めての Raspberry pi 〜プラレールをunityの世界の中で走らせよう〜 (1)
初めての Raspberry pi 〜プラレールをunityの世界の中で走らせよう〜 (1)
dcubeio
BizReach x Marketo連携
BizReach x Marketo連携
dcubeio
Kinesis Firehoseを使ってみた
Kinesis Firehoseを使ってみた
dcubeio
Apiドキュメンテーションツールを使いこなす【api blueprint編】
Apiドキュメンテーションツールを使いこなす【api blueprint編】
dcubeio
春の脆弱性祭り 2017/06/13
春の脆弱性祭り 2017/06/13
dcubeio
DynamoDBを導入した話
DynamoDBを導入した話
dcubeio
Play2 scalaを2年やって学んだこと
Play2 scalaを2年やって学んだこと
dcubeio
すごーい!APIドキュメントを更新するだけでAPIが自動テストできちゃう!たのしー!
すごーい!APIドキュメントを更新するだけでAPIが自動テストできちゃう!たのしー!
dcubeio
20170329 D3 DBAが夜間メンテをしなくなった日 発表資料
20170329 D3 DBAが夜間メンテをしなくなった日 発表資料
dcubeio
Bitcoin x Slack でマイクロペイメントを実現! 〜生活の必要上割り勘botを作るまで〜
Bitcoin x Slack でマイクロペイメントを実現! 〜生活の必要上割り勘botを作るまで〜
dcubeio
【freee】プロダクトマネージャーの仕事と魅力
【freee】プロダクトマネージャーの仕事と魅力
dcubeio
【ビズリーチ】プロダクトマネージャーの仕事と魅力
【ビズリーチ】プロダクトマネージャーの仕事と魅力
dcubeio
Python × Herokuで作る 雑談slack bot
Python × Herokuで作る 雑談slack bot
dcubeio
HR Tech x 機械学習 導入事例紹介
HR Tech x 機械学習 導入事例紹介
dcubeio
Scalaマクロ入門 bizr20170217
Scalaマクロ入門 bizr20170217
dcubeio
More from dcubeio
(20)
AWS Summit Tokyo 2019登壇資料「DevOpsの劇的改善!古いアーキテクチャから王道のマネージドサービスを活用しフルリプレイス! 」
AWS Summit Tokyo 2019登壇資料「DevOpsの劇的改善!古いアーキテクチャから王道のマネージドサービスを活用しフルリプレイス! 」
20170329 D3 DBAが夜間メンテをしなくなった日 発表資料
20170329 D3 DBAが夜間メンテをしなくなった日 発表資料
ビットコインとブロックチェーンを初めからていねいに(超基礎編)
ビットコインとブロックチェーンを初めからていねいに(超基礎編)
20171206 d3 health_tech発表資料
20171206 d3 health_tech発表資料
Go初心者がGoでコマンドラインツールの作成に挑戦した話
Go初心者がGoでコマンドラインツールの作成に挑戦した話
初めての Raspberry pi 〜プラレールをunityの世界の中で走らせよう〜 (1)
初めての Raspberry pi 〜プラレールをunityの世界の中で走らせよう〜 (1)
BizReach x Marketo連携
BizReach x Marketo連携
Kinesis Firehoseを使ってみた
Kinesis Firehoseを使ってみた
Apiドキュメンテーションツールを使いこなす【api blueprint編】
Apiドキュメンテーションツールを使いこなす【api blueprint編】
春の脆弱性祭り 2017/06/13
春の脆弱性祭り 2017/06/13
DynamoDBを導入した話
DynamoDBを導入した話
Play2 scalaを2年やって学んだこと
Play2 scalaを2年やって学んだこと
すごーい!APIドキュメントを更新するだけでAPIが自動テストできちゃう!たのしー!
すごーい!APIドキュメントを更新するだけでAPIが自動テストできちゃう!たのしー!
20170329 D3 DBAが夜間メンテをしなくなった日 発表資料
20170329 D3 DBAが夜間メンテをしなくなった日 発表資料
Bitcoin x Slack でマイクロペイメントを実現! 〜生活の必要上割り勘botを作るまで〜
Bitcoin x Slack でマイクロペイメントを実現! 〜生活の必要上割り勘botを作るまで〜
【freee】プロダクトマネージャーの仕事と魅力
【freee】プロダクトマネージャーの仕事と魅力
【ビズリーチ】プロダクトマネージャーの仕事と魅力
【ビズリーチ】プロダクトマネージャーの仕事と魅力
Python × Herokuで作る 雑談slack bot
Python × Herokuで作る 雑談slack bot
HR Tech x 機械学習 導入事例紹介
HR Tech x 機械学習 導入事例紹介
Scalaマクロ入門 bizr20170217
Scalaマクロ入門 bizr20170217
こんなに使える!今どきのAPIドキュメンテーションツール
1.
こんなに使える!今どきの APIドキュメンテーションツール 2016/10/25 権藤 尚樹
2.
自己紹介 ● 権藤 尚樹 ●
ビズリーチ ● スタンバイ事業部 ● バックエンドエンジニア ● Scala書いてます ● 一人旅が好きです
3.
日本最大級の求人検索エンジン「スタンバイ」
4.
いろいろ検索してみてください
5.
スタンバイの開発はマイクロサービス化 ● 複数のAPIに分けている ● チームも細かく分かれている ●
分業化も進めている
6.
APIドキュメント書いてますか?
7.
APIドキュメントは書くことが多い ● Host ● Path ●
HTTPメソッド(GET, POST, PUT, DELETE, ...) ● Request Header, Body ● Query Parameter ● Response Status Code ● Respose Header, Body ● Authrozation, Authentication ● etc...
8.
APIドキュメントは読みやすく ● 作るのはサーバーサイドエンジニア ● 読む人は様々 ○
フロントエンドエンジニア ○ ネイティブアプリエンジニア ○ マイクロサービスの場合、他チームのサーバーサイドエンジニア ● フォーマットを統一する必要がある ○ 表形式では限界がある
9.
JSON Schemaについて少し
10.
JSON Schemaとは ● JSONの型をJSONで定義する ●
細かい定義が可能 ● ライブラリやバリデーションが充実している
11.
JSON SchemaではAPIドキュメントは書きづらい ● あくまでJSONを定義するためのフォーマット ●
APIドキュメントを書くために作られたものではない ● (個人的には)そもそもJSONを書きたくない! ● アプリケーションの開発時には使える ○ 覚えることは少ない ○ 各種バリデーション ○ モデルのGenerate
12.
APIドキュメンテーションツール
13.
APIドキュメンテーションツール 1. Swagger 1.1. Swagger
Specification 1.2. Swagger UI 1.3. Swagger Editor 1.4. Swagger Core 2. API Blueprint 2.1. Specification 2.2. aglio
14.
Swagger ● Swagger Specという定義ファイルで管理 ●
歴史は古く、コミュニティ規模は大きい ● Open API Initiative というREST APIの標準化を推進する団体ができた ○ ツールとしてswaggerを使っている
15.
Swagger Specification ● JSON
or YAMLで定義 ○ ver2.0からYAMLに対応 ● schemaの部分は、JSON Schema Draft4を ベースとしている ● GFM(Github Flavored Markdown)が使える ● モデルはdefinitionで分割可能 ● 詳細はこちら ○ http://swagger.io/specification/
16.
Swagger Specification ● 全体の情報 ○
swaggerのバージョン ○ アプリケーションの情報 ○ ホスト ○ パス ○ プロトコル ○ Mime Type
17.
Swagger Specification(paths) ● endpointごとの情報 ○
HTTPメソッド ○ 説明 ○ リクエストパラメータ ○ レスポンス
18.
Swagger Specification(definitions) ● モデルの情報 ○
メンバ名 ○ 型 ○ 説明 ○ 必須かどうか ● JSON Schemaとほぼ同じ ● $ref属性で分割可能
19.
Swagger UI ● Specをもとにドキュメント化 ●
デモサイト: http://petstore.swagger.io/ ● インタラクティブなドキュメントが特徴 ● サーバーを立てれば、ブラウザ上でリクエスト を送ったりできる ● 実態は静的HTML + jQuery ○ カスタマイズもできる
20.
Swagger Core ● プロダクトコードから自動生成する ●
基本的にはコメントやアノテーションをつける タイプが多い ● javadocのようなイメージ ● 様々な言語のフレームワークで対応
21.
Swagger Editor ● specをブラウザ上で編集できるツール ●
デモサイト: http://editor.swagger.io ● 実際にリクエストを送りながら編集ができる ● ローカルにインストールもできるが、 Web上 のもので事足りる
22.
Swagger Codegen ● 定義ファイルからソースコードを生成 ○
モックサーバーのソースコードを作れる ○ Client側のモデルのソースコードを作れる ● 様々な言語のフレームワークに対応 ● Swagger Editor画面の左上にもついてる
23.
Swaggerの良い点 ● コードアノテーションで生成できる ○ ソースコードとドキュメントの乖離がない! ○
他のドキュメンテーションツールにない強み ○ テスト環境を用意する必要もない ● Swagger UIのインタラクティブドキュメントは便利 ● 高機能 ○ swaggerの各種ツールが充実している ● 各種言語・Webフレームワークの対応が手厚い ● 外部ツールも対応している ○ Postman ○ Amazon API Gateway
24.
Swaggerのイマイチと感じる点 ● Swagger UIが少し使いづらい ○
インタラクティブに動かすには Webサーバーが必要 ○ カスタマイズが必要なケースもある ○ API Blueprintのaglioと比べると見た目が ... ● アノテーションは賛否両論 ○ モデルのClassがきちんと定義されている必要がある ○ コードがアノテーションだらけになるため、見づらくなる ○ 各フレームワークのバージョンと対応状況に注意
25.
Play2(scala)のSwagger Core ● 別プロジェクトで動いている ○
https://github.com/swagger-api/swagger-play ● 公式のものは残念ながらplay2.4まで対応、2.5は対応中 ● (個人的には)ちょっと触った限り、少し面倒なところがある ○ Enum等のカスタムクラスの変換が難しそう ○ 別途annotationを加えればいけるが、記述量は多くなる
26.
API Blueprint
27.
● Markdownを使って定義を書く ○ 拡張子は.apib ●
Markdownそのままでも読みやすい ○ aglioを使うとさらに見やすくなる ● 専用のエディターはないが、Atomエディタのプラグインあり ○ https://atom.io/packages/api-blueprint-preview API Blueprint
28.
Specification ● 基本情報 ○ タイトル ○
ホスト ● グループ ○ swaggerでいうtags ● 各endpointの処理 ○ HTTPメソッド ○ endpoint ○ リクエスト ○ パラメータ ○ レスポンス
29.
Specification ● Data Structuresでモデルを定義 ○
swaggerでいうdefinitions ● メンバの情報は一行で記述する ○ メンバ名 ○ サンプル値 ○ 型 ○ 説明
30.
aglio ● API BlueprintをHTMLドキュメントに変換 ●
とても見やすい ● JSON Schemaを出力してくれる
31.
こんな感じに出力してくれます
32.
JSON Schemaも出してくれる
33.
API Blueprintの良い点 ● Markdownだけで直感的に書ける ●
自由に書きやすい ● シンプルにまとまっており、使いやすい ● aglioのHTMLドキュメントは素晴らしい
34.
API Blueprintのイマイチだと思う点 ● Swaggerほど高機能ではない ○
コードアノテーションのような機能はない ● 細かいスキーマの定義ができない ○ JSON Schemaでいうところのmaxlength, minlength, patternなど ○ コメントとして書くことである程度対応はできる
35.
ドキュメントが正しいか確認する
36.
Specファイルをもとにテストができる ● ドキュメントどおりの実装になっているか確認できる ● レビュー時に誤りに気づきやすい ●
レビューアの負担が減る
37.
1. Swagger Test
Template 2. Dredd テストツール
38.
Swagger Test Template ●
SpecファイルからJavascriptのテストコードを 自動生成して実行 ● Swagger Nodeの機能に組み込まれている
39.
Swagger Nodeについて少し ● https://github.com/swagger-api/swagger-node ●
Node.jsだけで一通り使えるようにしたもの ● 基本的なライフサイクル ○ specを書く ○ APIを実装する ○ テストコードを自動生成 ○ テスト実行 ● API Design First的な開発に向いている
40.
Swagger Test Templateを使ってみて ●
導入はすぐにできた ○ https://github.com/swagger-api/swagger-node ○ http://apigee.com/about/blog/developer/swagger-test-templates-test-your-apis ● Specが増えるに連れ、運用面で障害になった ● リクエストパラメータを指定できない ● 自動生成とはいえ、テストコードを毎回作らないといけない ○ 共通の定義が変わると全部作り直す必要がある
41.
Dredd ● apiary.ioが提供しているテストフレームワーク ● API
Blueprintとswaggerのspecファイルを実行可能 ● テストの設定ファイルをyamlで管理 ● 各種CIツールにも対応
42.
Dreddの良いところ ● テスト結果がわかりやすい ○ コンソール上の情報でも十分わかる ○
特にエラー時に役に立つ ○ ログレベルも変更可能 ● リクエストパラメータを指定可能 ○ sample値を指定する必要はあるが、それだけで済む ● テストするendpointを指定可能 ○ 設定yamlのonlyに配列で指定可能 ● hook処理を追加すれば細かい処理が可能
43.
hookとは ● テストに前処理・後処理を加えることができる ○ beforeAll,
afterAll ○ beforeEach, afterEach ● 特定のendpointに対してのみ追加することできる ○ before, After ● 用途は様々 ○ DBのレコードの初期化・掃除 ○ 認証・認可 ○ 個別のテスト ● いくつかの言語で書ける ○ Go, Node.js, Perl, PHP, Python, Ruby
44.
まとめ
45.
● 学習コストはどちらも同じくらい ○ yamlを書くかmarkdownを書くかアノテーションを書くかの違いぐらい ●
ドキュメント重視ならAPI Blueprintがおすすめ ● 定義を細かく書くならSwagger SpecをYAMLで ● 厳格に管理するならSwagger Coreのアノテーションで ドキュメンテーション編
46.
テスト編 ● テストを実行するならDreddがおすすめ ○ さらに言えば、Dreddを採用するつもりなら
API Blueprintのほうが良い ● テストを実行しないという選択肢もある ○ レビューや運用でカバーする
47.
プロダクトやチームにあった方法を用いる ● 導入の際は開発メンバーでよく話し合うこと ○ やること、やらないことを決める ●
開発の障害にならないように進めること ○ テスト環境を揃えるのは思ったよりも大変 ○ ドキュメントだけで十分ならば、レビューをしっかりやるのでも良いと思う ● 途中でツールを変えるのは大変 ○ 相互変換するライブラリもあるが、完璧ではない ○ 両方覚えるのは大変 ● テストを過信しないこと ○ オプショナルの項目が増えてもわからないこともある。レビューはしっかりと
48.
参考にしたサイト ● APIドキュメントを支える技術 ○ http://qiita.com/taizo/items/5a969ace57394a2d5b4a ●
API Meetup Tokyo #15 〜OpenAPI Specification (Swagger)特集〜の勉強会に 参加してきた ○ http://tsuyoshi-nakamura.hatenablog.com/entry/2016/07/25/114347 ● API Blueprintとその周辺ツール ○ http://qiita.com/sheepland/items/b4a0d03941f2e3cd8eaa
49.
サンプルコード置いてます ● https://github.com/n-gondo123/api-doc-example
50.
おまけ
51.
RAMLも面白そう ● 割と新しめのAPIドキュメンテーションツール ● yamlで記述する ●
swaggerと似ている ● 「swagger vs api blueprint vs raml」で検索すると面白い記事が見つかる
52.
ご清聴ありがとうございました。
Download now