はじめにこんにちは、Finatext で保険事業のプロダクト開発をしている @toshipon です。今回は以前の Fin-JAWS のイベントで少し紹介させていただいた、我々の現場で取り組んでいる、大規模API開発における Swagger を用いたAPI仕様のドキュメント運用方法について紹介いたします。 概要我々の現場では、API ベースのWeb Application を開発する際に、Swagger を用いて API 設計をしたり、BFFサーバー開発者やフロントエンド開発者とのコミュニケーション手段として活用しています。 ただし、Web Application の規模が大きくなってくると、Swagger の 定義ファイルは肥大化してしまい、メンテナンスが困難になってきます。 今回は、Web Application の規模が大きくなっても耐えうる Swagger 定義ファイルの運用方法を

背景 2020年4月に六本木のToC向けメディア系サービスを運営する企業に新卒入社した社会人1年目のエンジニアです。入社する1年前から始めた内定インターンではサーバーサイド開発はGolangを使っていましたがメインの開発はVue.js/Nuxt.jsでのフロントエンド開発であった為、Golangは殆ど初心者レベルでした。今回は勉強目的でTODOアプリ用のAPIサーバーを0から開発したので、そのノウハウなどをこの記事で共有できればと思っております。 この記事の対象者 Golangを勉強し始めた初心者の方 Golangを使ってサービスを開発したいと考えている初心者の方 アーキテクチャ 次のような簡易なアーキテクチャにしました。言葉で説明するとちょっと長くなりそうなのでdocker-compose.ymlを添付しておきます。 version: '3' services: app: build:

久々に開発ネタです. 大晦日ハッカソン2019 #大晦日ハッカソンで, 野球のデータをシュッと見るためのDashboardを作る（理由は後ほど）. そんなDashboardのBackend APIをシュッと開発する. を目標に立て現在進行系でやってるのですが, 午後の進捗その2 Docker化が特に滞りなく完了. API Docも見れるとかFast API強すぎぃ 昨日の夕方から開発してたAPIはアッサリ1st Ver.できたので, 大晦日の買い物終わったらフロントエンドを除夜の鐘が鳴るまでになんとかするぞ #大晦日ハッカソン pic.twitter.com/wWMiSvQDKu— Shinichi Nakagawa (@shinyorke) 2019年12月31日 Backendを昨日（12/30）の18:00から着手して（実質作業時間）約5時間ちょいで完成させてしまいました. 本年最後

PythonのWeb frameworkで、Flaskのようなマイクロフレームワークにあたります。 パフォーマンスの高さ、書きやすさ、本番運用を強く意識した設計、モダンな機能などが強みです。 FastAPIはStarletteの肩に乗る形で書かれており、非同期処理が扱いやすいです。 特に、以下の様な特徴があります。 ASGI websocketのサポート GraphQLのサポート バックグラウンドプロセスが扱いやすい python type hintによる自動ドキュメント生成 (Swagger UI) pydanticをベースとしたdata validation 率直に言って、responderに非常に似ています。(でた時期も近いですし、responderもStarletteがベースなので) ですが、下の2つはFastAPIの方がよっぽど使いやすく設計されています。 以下の観点から総合的に

You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert

サーバーサイドエンジニアのいわむ(@k_iwamu)です！ 実は来月AWS re:Inventに参加してきます！弊社は海外カンファレンス補助が充実しているので、そういった配慮に感謝してたくさんのことを学んできます！ さて、社内ではFammを中心としたいくつかのサービスや社内システムで複数のAPIが開発されています。会社の規模も大きくなるにつれ、それぞれのサービスを社内のエンジニアで分担しながら作っています。 そうした中で、２つの課題があげられるようになりました。 - サービスごとにAPIドキュメントの運用方法やフォーマットが統一されておらず、管理が難しい状況になっている - APIドキュメントをホスティングするためにサーバーが立ち上がっており、その管理も必要になっている そこで考えられた方針が、Swaggerを使ってドキュメントを統一化し、S3を使ってホスティングする方法です。理由は以下で

はじめに 私の職場では、WebAPIの仕様書をWordで書く習慣があったのですが、2018年頃にSwaggerで書くように切り替わったので、そのように変化した経緯を書きます。 何かの参考になれば幸いです。 ちなみに、こちらの記事と同じ職場です。 Wordな職場にMarkdownを定着させるためにやった４つのこと Swaggerとは？ Swaggerとは、REST APIの仕様を定義するためのフォーマットです。その周辺技術も含めて、Swaggerと呼ばれます。以下の記事が非常に参考になりますので、詳細を知りたい方はご参照ください。 Swaggerの概要をまとめてみた。 Swagger 導入失敗 2016年頃のある日、上司から「世の中にはSwaggerというものがあるらしい。調べてもらえる？」と指示されました。 調べてみたところ、Swaggerがあれば、WebAPIのドキュメントサイトも作れる

Go のフレームワークに求めるものこの場合、フレームワークに対して何を求めるでしょうか。 私は以下を重要視していました。 重要視したことドキュメントと実装の乖離をなくすことで、認識齟齬なく開発を行うこと なぜ？ ドキュメントと実装のズレを解消するコストが高いため Web API 開発をする中で最も困ることは ドキュメントと実装がかけ離れること です。ドキュメントととのずれによる、コミュニケーションを極力減らしたいと考えました インタフェースが頻繁に変わることが想定されたため データ定義の部分が固く決まっていなかったため、データに引きずられて API 仕様の変更も頻繁に起きるだろうと思いました インタフェースのやり取りの物理的な距離が遠いため 同一の会社内だけでなく会社間をまたいだ開発も想定されたため、コミュニケーションコストがより高くなると想定しました フレームワーク比較ドキュメントと実装

サードパーティ製のツール本家からは上述のツールが提供されていますが、サードバーティ製の様々なツールが世の中には存在します。 エコシステムが成熟しているのもSwaggerを利用するメリットの1つですね。 https://openapi.tools/ 冒頭のとおり、このサードパーティ製のツールの中で実際に利用して良かったツールを3つご紹介したいと思います。 Stoplight Studiohttps://stoplight.io/studio/ 1つ目のツールは「Stoplight Studio」というAPI仕様を記載するためのGUIエディタとなります。 今までSwagger Editorを利用してYAMLを書いていたそこのみなさん、YAML筋力はもう必要ありません。 Design APIs 10x faster の謳い文句どおり、Stoplight Studioを使えばGUIで直感的に、高速

こんにちは、エンジニアリンググループの福林 (@fukubaya) です。 先月から、今年の秋くらいにリリース予定の新サービスの設計、開発を始めました。 せっかく新しく始めるサービスなので、まだ経験したことがない言語やフレームワーク、技術を使わないと楽しくありません。 そこで、バックエンドにGoにして、フロントのAPIまで含めてgRPCの .proto ファイルで定義を一元化し、APIコードは protoc で生成させる計画を立てていたのですが、 フロントでgRPCとなると、 gRPC-web か grpc-gateway になるが、リリースまでに使える期間では認証も含めると検証が間に合わなさそう Goだけでなく、terraform(インフラ設計もやります) も Vue.jsも今回が初めて、というメンバーもおり、さらにRESTではなくgRPCも、となると未経験技術が多すぎてキャッチアップが

こんにちは、インダストリー事業本部 医療チームの高橋（@yukey1031）です。 去年のクリスマス以来の投稿です。AMIAS（アミアス）をお願いします。 さて、今回は自身の周辺業務で普段行っているOpenAPIによるスキーマファースト開発の実施サンプルと先日Google Cloudより発表された「Cloud Run」について少し触れてみたいと思います。 なお、フロントエンドはVue.js+TypeScript+Axios、バックエンドはJava+SpringBootでの話です。 マイクロサービスな現場でのAPI開発 スキーマファースト開発 OpenAPI OpenAPI Generator Cloud Run 実施サンプル Requirement インターフェイス定義 サーバーサイド実装 フロントエンド実装 Cloud Runにデプロイ／接続 おわりに マイクロサービスな現場でのAPI開

Swaggerについて THE WORLD'S MOST POPULAR API TOOLING 世界で最も人気のあるAPIツール 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. Swaggerは、OpenAPI仕様（OAS）のためのAPI開発ツールの世界最大のフレームワークであり、APIのライフサイクル全体にわたって、設計から文書化、テストおよびデプロイまでを可能にします。 https://swagger.io 特徴 YAM

はじめに こんにちは！ 2019年2月にZOZOテクノロジーズへサーバーサイドエンジニアとして入社した籏野（@gold_kou）と申します。 Qiitaでも少し記事書いてます。 いきなりですが、皆さんはAPI仕様書をどのように管理されていらっしゃいますか？ Confluence、Wiki、Markdown、Spreadsheet、Excelなど色々手段やツールはあると思います。私が担当しているプロジェクトではOpenAPIを導入しています。 この記事ではOpenAPIの基本と実際に導入して得られたノウハウをご紹介いたします。 OpneAPIの恩恵はただの管理の仕方にとどまらないので、ぜひこの記事を読んで開発効率化のお役に立てばと思います。 また、弊社のテックブログで以前、OpenAPI(Swagger)のバージョン2系に関する開発効率を上げる！Swaggerの記法まとめ や 開発効率を上げ

はじめに APIエコノミーが盛り上がっています。例えばTwitterのようにツイートデータを公開したり、Googleのように画像処理や自然言語処理の技術を公開するのにWebAPIが使われています。 他には、障害に強いサービスを作るためにアーキテクチャをモノリシックからマイクロサービスに移行する動きがあり、マイクロサービス間はWebAPIで繋がっています。 現代においてWebAPIは必要不可欠なインターフェースであり、だからこそWebAPIの設計は非常に綿密に行う必要があります。 今回は、Swaggerを利用したWebAPIの設計方法についてまとめました。 目次 1. APIを設計する前にRestful WebAPIの基礎を学ぶ2. 仕様を考える3. 詳細設計をする4. コーディング5. APIを試用するおわりに 1. APIを設計する前にRestful WebAPIの基礎を学ぶ 下記は良書

以下記事を試行済みの想定. django rest framework : viewset description rest framework で作成した api の一覧を自動生成する. swagger module を用いる swaggerとは 以下参照されたし Swaggerの概要をまとめてみた 参考動画 有効化済み path 一覧が表示される swagger module install

この記事はGoCon 2016 springで話す内容を圧縮するためのものです。 WebサービスのAPI仕様を記述したりするためのそれなりに有名な仕様について、筆者(@vvakame)の私見を述べていく。 なお、Google Trendの結果を見ると…。 仕様を調べてSwaggerを選択する事にしたのは1年弱程度前のはずなので、もし "今はそれもうできるよ！" とかあったらコメントなどで教えてください。 RAML RESTful API Modeling Language なので、手書きを前提にしている。 YAMLで頑張って仕様を書く。 Spec APIs Explorerっぽいものもあるっぽい。 総評 比較的広く使われているようでパワを感じる。 まず仕様が先というスタイルなのがめんどくさそう。 YAMLなのがちょっとイヤ。 RAMLからGoとJavaScript(TypeScript)向

最近のウェブ開発では各機能ごとをAPIでつなぎ込む時代になっています。 そのため、各チームが開発をしていく上で、 他のチームにAPIの仕様を伝える方法をきちんとまとめておく必要が出てきています。 そんな中でAPIドキュメントにどのような役割が求められていて どのような選択肢があるか、一旦自分の把握している知識をまとめています。 (ここで書いているAPIは、httpでアクセスしたら、JSON形式でレスポンスを返すウェブサービスのAPIを指しています) APIドキュメントを用意する上で、すぐにぶつかる壁 APIドキュメントを用意する場合に、何も考えずにExcelやwikiにまとめると、早い段階で メンテナンスのコスト の問題にぶつかります。 『APIドキュメントを書く時間がない』 『本当にドキュメント通りの結果が返ってくるか、試してみないとわからない』 『実際に返ってくるAPIとレスポンスが違

こんにちは、まちいろの工藤です。 まちいろでは開発フレームワークに Rails を採用していますが、最近の新規案件では Go 言語を採用してみています。この記事では、Go で開発を始めるにあたって行ったライブラリ選定の中身を紹介したいと思います。 選定にあたっては、awesome-go や Qiita などの記事を参考にしました。 ModulesGo 1.11 から Go modules が導入されたとのことで、素直に Go modules を利用することにしました。特にハマることもなく利用ができています。 Web Application FrameworkgRPC + grpc-gateway or grpc-web ・https://github.com/grpc/grpc-go ・🙆proto でスキーマ駆動開発が可能 ・🙅‍♂️REST API を提供する場合は grpc-ga