swaggerとは 古の時代、API仕様書はwordやexcelで表現され、各所に共有されるというのが一般的でした。 ですが近年、API仕様を表現する際にはswaggerを利用するのが最も効率的で、保守性が高く、世間一般で仕様化され、見やすいというのもあり、一般化されてきたのではないのでしょうか 今回はそんなswaggerの書き方について、まずは書くために覚えておきたいポイントを解説していこうかと思います！ どう書いてくか swagger editorで書く 公式がWeb上に提供しているツールを利用し、すぐにでもswaggerの執筆が可能となっています！ なにをインストールする必要もなく開始1秒で利用できるので、私も重宝してます なお、ページを開くとサンプルAPI仕様がすでにある状態でのスタートとなり、記法の参考などにもなります vscodeで書く 必要なプラグインをインストールし、vsc

前回は「今日から始めるswagger入門」という最低限書けるようになっておいた方が良い物をこちらの記事で解説させてもらいました 今回は、筆者が4〜5年ほど現場で見てきたswaggerを元に、現場で必要になるswaggerの知識をまとめましたので、ぜひご覧になっていただけると嬉しいです！ タグ付け pathsに書かれている各APIendpointをタグ付けしてグルーピングする目的で使用されます 現場では大量のAPIendpointを設計していくこととなるので、多くなってくると大変見辛くなってきます それをグルーピングすることにより見やすくしようということです openapi: 3.0.3 info: title: test-api version: 0.0.1 # ここから tags: - name: user description: ユーザー情報 # ここまで paths: /users

はじめに 自分は実務でReact×TypeScriptを利用したフロント周りとNode.js(Nest)やRailsを用いたバックエンド(API)の開発をしています。 本記事では、OpenAPIを用いたAPI設計の書き方及び、Swaggerの説明と使い方についてまとめていきます。 この記事の対象者 プログラミング初心者から中級者 APIの基礎を理解している人 OpenAPIを用いてサクッとモックサーバーを試したい人 この記事の目標 モックサーバーの環境構築を学ぶ Swaggerの使い方を理解する OpenAPIを用いてAPI設計の具体的な書き方を学ぶ この記事でやらないこと 本記事ではOpenAPIの「書き方」をメインで解説するため、API設計についての細かい解説は省きます。 なおAPI設計については下記の記事でまとめているので、ぜひ参考にしてみてください。 用語解説 OpenAPI 公式

DX事業部の @yyoshiki41 です。 今回は、今年1月にリリースしたLayerX インボイス のアプリケーション開発についてです。 インフラ構成については、昨日のLayerX インボイスのインフラアーキテクチャで紹介されています。 tech.layerx.co.jp LayerX インボイスというプロダクトの特徴 LayerX インボイス は、主に経理業務を行う方を対象ユーザーにした SaaS プロダクトです。 サービス内で以下の業務を行うことがメインになっています。 請求書の受領 請求書から仕訳を行う オンラインバンキングに取り込むためのデータを出力する 会計ソフトに仕訳データを連携する また上記の他にも マスタデータ（例えば、仕訳データの入力に使う取引先や部門、税区分など）の管理や会計ソフトへの連携 源泉税の支払管理 請求書の社内での確認 などを行う機能が実装されています。 エ

自分の本業は10年物のMVCプロジェクトなのでClean Architecture忘れがちです。 なので、慣れてるGoでパッとClean Architectureの復習を行ってみました（２年前にPythonでやった事はあるんだけど・・・）。 このスクラップでは単語とか作りどころとかを整理するのですが、また後でRustで作ってそっちは前例がほぼないので記事にします。 Go + Clean Architectureは結構記事あるんですが、Swaggerつけたしたのと自分なりに納得いくディレクトリ構成にオリジナリティを出しました。ちなみにgo-swagger使うと本当は凄く楽に作れるのですが(ついでにフロントはopenapi-generator)、今回はClean Architectureを理解するのが主目的なので、サーバーは手書きでopenapiのyamlも1から自作しました。 ↑ postに

こんにちは。LINE Growth Technology福岡開発室でサーバーサイドエンジニアをしている中村です。 この記事では担当していたプロジェクトで実施した、Swaggerを使ったAPIドキュメントの作成と、BE（バックエンド）とFE（フロントエンド）間の連携について紹介します。 プロジェクトの説明 はじめに、今回LINE Growth Technology福岡開発室（以下「GT」）がシステムの設計開発を担当した、LINE公式アカウント審査ツールのプロジェクトについて説明します。 LINE公式アカウント審査ツールとは、LINE公式アカウントで認証済アカウントが申請された際に、申請内容が適切であるか審査するシステムです。 このシステムは、LINE公式アカウントが利用されている各国に存在する審査パートというチーム（以下「審査チーム」）によって利用され、日本以外の国家も含め、一日あたり平均約

チームでのWeb API開発において、進行を妨げる要因は様々な形で噴出します。 「フロントはバックエンドのAPI実装待ちなので動けません...」「ドキュメンテーションのコストが重い...」「ドキュメントと実装が全然違うので参考にならない...」 また、APIスキーマ設定が不十分だと、ビジネスドメインの最低原則やクライアント側のニーズを理解せずに、バックエンド都合のAPIがそのまま実装される危険性もあります。 そうした問題を解決すべくSchema Driven Developmentと呼ばれる開発手法が生まれました。 Schema Driven Developmentとは？ Schema Driven Development(以下SDD)とはチームにおけるWeb API開発フローを改善する開発手法の一つです。スキーマ駆動開発やSchema First Developmentとも呼ばれています

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article?

はじめにTIG DXユニット 1の真野です。echo → 生net/http → gorilla/mux → go-swagger, gqlgenの経歴でGoのHTTP APIを実装してきました。本記事では最近業務でヘビーユーズしているgo-swaggerについての開発Tipsをまとめました。 背景フューチャーではGoを採用する案件が増えて来ており、その際にgo-swagger というツールを利用することが多いです。 2 理由はWeb APIのスキーマを駆動に開発することに慣れているという開発文化（DBレイヤのERDやデータフローを駆動に開発することは今も多い）や、リリース後の保守や将来のマイグレーションを考慮しなるべく特定のDSLに依存したくないというポリシーを強く持つこと、開発前にある程度固く機能数を洗い出して工数見積もりや開発スケジュールに活かしたいといった大人な事情など、色々相性が

swaggo 今回紹介するswaggoはyvasiyarov/swaggerにインスパイアを受けて、作成したOSSになります。現在、yvasiyarov/swaggerは開発が止まっているので、いくつかの問題が放置されたままになっています。（これはOSSなので仕方ないです） swaggoは元の構文をそのまま流用して、機能追加をしているものになります。 Swagger 2.0の対応 複雑な構造体の解析 カスタムヘッダー example value セキュリティ 私がざっと見た限り、上の内容はswaggoで無ければ使えないっぽいです。 Swagger便利だけど、書くのがそもそもだるい 最近になって、よくSwaggerというワードを目にするようになりました。これはとても画期的で、APIに実際にリクエストを投げれるドキュメントが出来上がります。 しかし、このドキュメントのコードを書くのが結構面倒！

はじめまして。TIG DXユニット 1の亀井です。 はじめに みなさん、Swagger使ってますか？ Swaggerや周辺ツールについては 某先輩の記事 にて丁寧に解説されていますので、 本記事では実際にSwaggerのスキーマ定義を設計していく上で取り決めた規約について書いてみたいと思います。 前提私が在籍しているプロジェクトでは、REST APIは golang でフロントエンドを Vue.js + TypeScript で構築しています。 短期間・高品質での構築を実現するためにSwaggerを設計ドキュメントとしてだけではなく、コード自動生成やモックサーバーに活用させることで徹底したスキーマファーストな開発を行ってきました。 というわけで、今回は下記のツールを利用することを前提として規約を作成しています。 go-swagger: Goアプリケーションのハンドラ、リクエスト/レスポンス

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

サードパーティ製のツール本家からは上述のツールが提供されていますが、サードバーティ製の様々なツールが世の中には存在します。 エコシステムが成熟しているのも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で直感的に、高速

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? 概要 GitHub 上で、Swagger の yaml | yml | json を Swagger-UI に変換できる Chrome 拡張機能を作った。 その紹介。 「Swagger とは？」という話は、下記等を参照のこと。 Swaggerの概要をまとめてみた。 - Qiita Demo クリックするだけ。簡単に変換できる。 全展開・全折り畳みができて便利。 インストール Chrome Web Store からインストールできる。 swagger-viewer - Chrome ウェブストア 特徴 簡単 1クリックで変換できる 依存な

こんにちは、まちいろの工藤です。 まちいろでは開発フレームワークに 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

connpass.com goa って何？ goa ってのは golang で APIデザインを書くと，そこから API サーバのモックとかクライアントとかドキュメントとか一通り生成してくれるマイクロサービス用のフレームワークのことです． goa は golang のソースとして DSL が書けて，そいつを goa にかけてやることでコードを生成します．ぱっと聞いた感じ，最初に抱く印象は「キモい」だと思うんですが，json や yaml を書いてコードを生成するよりかなり見通しよくAPIがデザインできると思いますし，なにより，goa の生成するコードがすごく読みやすいコードで，使ってるウチにだんだん「goa (キモ)かわいいな」と思うようになってきました．goa 自体のコードも変態的(コード生成プログラムなのでしょうがない)でありながら読みやすいコードで書かれているのも好印象です． Web

実際にMicroservicesを作る場合の話 必要な要件を並べてみましたが、自分のチームの場合、実際は上記の多くはApplication側で解決せずAWSやGCP、その他SaaS, PaaSの提供する機能で解決するようにしており、例えば下記のように対処可能です。 Load balancingはAWS ALB Message QueueはAWS SQS TracingはAWS Xray などなど。 とすると、Microservicesを開発する上で大切になってくるのは、チームが多くのAPIとやり取りするその過程を円滑にすることだと考えており、過去はそこをswaggerで記述してAPIデザインをレビューし合うことで解決しておりました。 ただし、課題としてAPIドキュメントを作成するフローと実際にAPIを作るフローが一連の流れにならない、ツールとして別々な世界の話になっているため、ドキュメント

2024-09-10 テクノロジア魔法学校の体験談と評判 「テクノロジア魔法学校」というプログラミング教材をご存知ですか？ ホームページの広告などで一度は目にしたことがある人も多いのではないかと思いますが、ディズニーが提供する子供向けのプログラミング教材です。 今回は、この「テクノロジア魔法学校」の体験版を実際に体験してみての感想や、「テクノロジア魔法学校」がどのようなものか、その評判などを見ていきたいと思います。 テクノロジア魔法学校とは 料金 エント […] 2024-09-10 レンタルサーバー「クイッカ」の評判と使い勝手 レンタルサーバーとして有名なサーバーの一つに、「クイッカ」があります。 名前は聞いたことのある人も多いのではないかと思いますが、今回はこの「クイッカ」について、料金やスペック、評判などを見ていきたいと思います。 レンタルサーバー「クイッカ」の基本情報 レンタルサー

REST API仕様からAPIクライアントやスタブサーバを自動生成する「OpenAPI Generator」オープンソースで公開。Swagger Codegenからのフォーク RESTful APIの仕様を基に、APIクライアント用SDK、APIクライアントのテスト用にAPIサーバのように振る舞ってくれるスタブサーバ、Webサーバのコンフィグレーション、ドキュメントなどを自動生成してくれる「OpenAPI Generator」がオープンソースとして公開されました。 RESTful API仕様の記述フォーマットは、2015年にマイクロソフトやGoogle、IBMらが立ち上げた「Open API Initiative」が提唱する「OpenAPI Specification」が事実上の業界標準となっており、OpenAPI GeneratorもこのOpenAPI Specificationを基に開

2018-05-12、OpenAPI Generator が公開されました。 https://github.com/OpenAPITools/openapi-generator OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec これは Swagger Codegen v2.4をフォークしたプロジェクトで、OpenAPIドキュメントから様々なプログラミング言語のAPIクライアントやスタブサーバーなどのソースコードを生成するツールです。まだベータ版のような状態で、“v3.0.0”として初回リリースすることを予定しています 。 私