ゆめみ その2 Advent Calendar 2019 23日目の記事です。 はじめに PostgreSQL のスキーマ情報から、自動的にGraphQLエンドポイントを作成する PostGraphile というツールを見つけたので試してみました。 PostGraphile https://www.graphile.org/postgraphile/ PostGraphile とは PostGraphile は PostgreSQL のテーブル、列、インデックス、リレーションシップ、View、型、関数、コメントなどを自動的に検出し、GraphQL APIを提供する Node.js 製のオープンソースソフトウェアです(以前は「PostGraphQL」と呼ばれていました)。 基本的な使い方としては PostgreSQL を用意して、コマンドラインから postgraphile コマンドに引数を

この抜粋の内容は次のとおりです。 Subgraph Server の実装 Gateway Server の実装 Subgraph を通す Gateway を通す さらに詳しく知りたい方は読み続けてください。 2023年7月4回目です。 GraphQL Fedetaion についてです。 弊社のモバイルアプリの1つは、ユーザーのネットワーク帯域幅による影響を避けるため、GraphQL を BFF として使っています。 単一ドメイン業務においては、1つの GraghQL で問題ないと思います。 しかし、複数のドメイン業務を扱う場合、各チームは独立して自分たちの GraphQL サービスを開発するため、Supergraph（GraghQL Federation）1 にしていく必要があると思います。 現在弊社の第1言語は、Go です。Go による GraphQL Federation について見て

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

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? 書きたいことを詰め込んだらタイトルが長くなってしまいました。 インフラ、フロントエンドと記事を書いてきたのでようやくバックエンドに触れます。 今回もサンプルを用意していますので最後までお付き合いください。 対象読者 マイクロサービス化を見据えたモノリシックアプリケーションを検討されている方 GraphQL サーバーと REST API サーバーのコードを共通化したい方 中規模以上のプロジェクト / プロダクトの技術選定を任された方 Scala や ZIO、関数型プログラミングに興味がある方 注意事項 サンプルはドメイン駆動設計(DDD)

はじめに 最近フロントエンドの通信をGraphQLに統一すべく頑張っているのですが、元々フロントエンドメインで開発していたのもありパフォーマンス度外視のBFF実装をしてしまいました。今回はGraphQLのパフォーマンス改善のために取り組んだこと2つをまとめていきたいと思います。2つしか書かない分できるだけ丁寧に書いたつもりです。普段BFFをGo言語で実装してるためサンプルコードはGo言語で書きますが、Goがわからない人にもわかりやすく説明するので最後までお付き合いいただけると幸いです。 触れること 取得するフィールドの制限してオーバーフェッチングを防ぐ Dataloaderを利用したN+1問題の解決 触れないこと GraphQLの基礎的なこと スキーマ設計とか 外部ツールを導入して計測をしたりだとか 現状そこまでしてパフォーマンス改善を行なった経験がないため 導入コストが高そうなので今回は

前期に初めて Relay Connection を使ったページネーション実装を行いました。 実装要件の制約もあり、その良さを最大限に生かした実装にはならなかったものの、カーソルベースのページネーションの考え方や Connection の仕様など、個人的に新しく学ぶことができました。 実際の実装イメージともに、それらの学びをまとめとして共有したいと思います。 前提 ページネーションの実装方式 そもそもページネーションの実装にはいくつか方法があり、代表してオフセットベースとカーソルベースがよく取り上げられます。 それぞれ得意とすることが異なるため、適材適所で使い分ける必要があります。 オフセットベースページネーション (offset-based pagination） SQL の OFFSET/LIMIT 句を使ったページネーション方式です。 データの先頭から数えて offset　で指定した数

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

この記事は セゾン情報システムズ Advent Calendar 2023 2日目の記事です。 はじめに GraphQLはAPIに関わる部分で、開発者にとっての利便性を向上させてくれるツールだと考えています。 例えば、 クライアント側からのリクエスト過多によるパフォーマンスを改善したい 強固な型安全性を担保したい Swagger的な役割のものが欲しい といったニーズに応えてくれると思っています。 ただし、クライアント側、サーバー側両方との連携が要求されるため考慮することは多くなります。 サーバー側であれば、データベース連携がその1つです。 この部分をなるべくシンプルに連携するために、Prismaを使用して検証してみました。 本記事では、GraphQLの基礎について理解を深めるとともに、Apolloを用いてGraphQLサーバーを実装し、Prismaとの連携手順を知ることを目的とします。 前

株式会社Neverのkousoです。 株式会社Neverは「NEVER STOP CREATE 作りつづけること」をビジョンに掲げ、理想を実現するためにプロダクトを作り続ける組織です。モバイルアプリケーションの受託開発、技術支援、コンサルティングを行っております。アプリ開発のご依頼や開発面でのお困りの際はお気楽にお問合せください。 https://neverjp.com/contact/ 概要 最近、graphQLを使用しているので、勉強のためにタイトル記載のパッケージを使用してみました。 色々なパッケージがある中、mutationやqueryをコード生成してくれるgraphql_codegen、キャッシュ機能があるgraphql_flutterが実際に活かせそうだと思ったので使用してみました。 GraphQLのAPI 今回はこちらを使用しました デモアプリ 20件取得して、次のページでさ

こんにちは。フリーランスで、主にRailsを使った開発の仕事をしている ymstshinichiro と申します。 直近約3年GraphQLの現場で仕事をしつつ、今年4月からはOpenAPIの現場でも並行で稼働しているのですが、両方を使ってみて個人的にGraphQLのここが良いなと思ったポイントをまとめてみました。 おことわり: 「これからGraphQLを使っていくべきか迷っている」という方へ向けた記事になったので、既にGraphQLをガンガン使いこなしている人には当たり前のことしか書いてないかもです あくまで僕の 好み・主観・経験 に基づく記事なので、その辺考慮の上で読んでいただけると助かります 記事中のサンプルコードはRailsで書かれています GraphQLを使うと自然にCQSに近づく 先日、YOUTRUSTさんが主催する実際のproductionコードを見ながら会話する勉強会 に参

ビットキーではこれまでメインのDBとしてFirestoreを使ってきましたが、現在RDBへの移行を進めています。 移行の理由としては、主にビジネス上のドメインが広がり、Firestoreにおける検索性能の弱さがネックになってきたことが挙げられます。 これまで検索性を補完するためにElasticsearchやAlgolia、検索用途のRDBなどを併用してきましたが、メインDBをRDBとすることで基本はサブのDBなしに運用できるようにしていきたいと考えています。 今回はオフィス領域のプロダクトである workhub において移行を進める際に、どのように実装したのかについて紹介します。 方針 今のところ、Pubsub等の非同期は使わずに同期的にRDBへデータを同期しています。 これは書き込み直後の整合性を重視するためです。 移行の単位は基本（一部の仕様整理まで踏み込んだもの以外）はコレクション単

これは GLOBIS Advent Calendar 2023 10日目の記事です。 はじめに こんにちは。GLOBIS学び放題でWebエンジニアをしている富山です。 GLOBIS学び放題のWebフロントエンドの構成は、React(TypeScript) / GraphQLで、GraphQLのクライアントライブラリには、Apollo Client + GraphQL Code Generatorを利用しています。 今回は、Apollo Clientのバージョンアップにより、Suspenseが利用可能になったので、本記事では、実際に学び放題のコードベースに適応しようとするとどうなるか検証してみました。 Apollo Client v3.8からSuspense対応された Suspense自体はReact18でリリースされたもので、Reactを利用してる方ならお馴染みの機能ですが、Relayやu

はじめに 今回はタイトルの通り、「GraphQLは「オワコン」「流行らない」のか？」という問に対して、個人的に調査した内容となります。 今回のタイトルで記事を書くことにしたのは、Googelの検索フォームに「GraphQL」と入力したところ、サジェストに「Graphql 流行らない」「Graphql オワコン」と表示されたことがきっかけです。 (試しにシークレットモードで入力してもサジェストされるので、私の検索履歴などのパーソナル情報によるバイアスはかかっていないはずです) 「Graphql オワコン」での検索結果TOPに「GraphQLはオワコンですか?これからはtRPCの時代ですか?REST APIの位置づけは何ですか?」というページがあったので読んでみました。 回答者はNodejsユーザグループ代表の古川さんで「GraphQLをオワコンと称するにはまだ早い」と回答されています。 私も

はじめに GraphQLConf 2023が2023/9/19-21で開催されていました。 そこで個人的に特に気になったのがOpen FederationやFusionといったGatewayの仕様周りの話題です。 これら2つは何が異なるのか、Apollo Federationと何が異なるのか、それらを実装したサーバにはどんなものがあるのか、等いくつか気になることがあったので、講演と自身で調べた内容を併せて紹介したいと思います。 ちなみにGraphQLConfはアーカイブをYoutubeで公開しているので興味ある方はぜひ。 想定読者 GraphQL Gatewayの歴史を知りたい方 GraphQL Gatewayについての知見を深めたい方 Open FederationとFusionの違いを知りたい方 GatewayとしてのGraphQLの歴史 元々はFaceBookでは以下のようなモノリシ

はじめに この記事では、バックエンドのコード生成が可能なGoのライブラリentとgqlgenを使用して、爆速＆省エネでGraphQLバックエンドの開発を行います。 GraphQLを用いたバックエンドの開発負担を、可能な限り軽減することが目的です。 自分用の備忘録でもあるため、蛇足な説明があるかもしれないです。ご容赦ください。 なぜGoでGraphQLバックエンドを開発するのか GraphQLは、クライアント側で必要なデータの形式や量を柔軟に指定できるAPI用のクエリ言語です。そのため、REST APIとは異なり、必要最低限のリクエストで必要なデータだけを抽出するすることができます。（オーバーフェッチの排除） 一方、リクエストパターンが増加することで、その分サーバー側の開発の負担が増加するというデメリットがあります。 そこで、サーバー側の開発負担を軽減しようと考えるのが自然かと思います。その

Step2. Secret Manager に DB 認証情報の保存 AWS AppSync は Amazon Aurora クラスターに接続する際に Secret Manager に保存されたシークレットを使用します。シークレットのタイプを「Amazon RDS データベースの認証情報」を選択肢、認証情報をデータベースを選択します。それ以外はデフォルトのまま、作成に進みます。 Step3. GraphQL API の作成 次に、GraphQL API を作成しましょう。GraphQL API データソースで「Amazon Aurora クラスターから始める - New」を選択し、次に進みます。 次に、API 名にわかり易い名前を入力します。今回はデフォルトの「My AppSync API」としました。 次にデータベースを選択します。 「データベースを選択」をクリックすると接続したい Am

背景 今まで GraphQL を Next.js と併用する場合、スキーマ情報をフロントエンドと共有するために graphql-codegen を用いて型を自動生成し、 apollo client や urql 向けのプラグインを用いてブラウザから直接 GraphQL リクエストを送信するクライアントを作り、受け取ったデータをコンポーネントに反映していた。 しかし RSC や Server Actions の登場により、ブラウザ上で直接 GraphQL リクエストを送信する必要がなくなり、Node ランタイム上で GraphQL リクエストのやりとりができるだけで十分になった。 そこで、とある新規プロジェクトでシンプルに GraphQL リクエストの送受信だけできるクライアントライブラリである graphql-request を採用した。 graphql-codegen が graphql

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

環境 java 17 spring-boot 3.1.2 graphql-java 21.0 発端 GraphQL API の利用者から「クエリが実行できない！」という報告を受けました。 報告があったエラーは以下。 graphql.parser.exceptions.ParseCancelledException: More than 15,000 'grammar' tokens have been presented. To prevent Denial Of Service attacks, parsing has been cancelled. メッセージを見てすぐに「巨大なクエリを送っているクライアント側の責任だろう」とは思いましたが、そんな制限を実装したつもりは無いし、 API ドキュメントでも明言していなかったので、発生源を確認しました。 サイズ制限エラーの発生源 ログにスタ

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? Relayとは Meta 製の GraphQL クライアント。 記事執筆時の最新バージョン：Relay v16.1.0 Cacheについて 一口にキャッシュにもいくつか種類があり、ここでは以下2つのキャッシュを扱う。 Query Cache（Document Cache） query単位のcache dataのこと consoleで以下オブジェクトに情報が格納されていることが確認できる __RELAY_DEVTOOLS_HOOK__.environments.get(1)._store._roots store生成時のoptionで有効

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? 自ブログからの引用です。 はじめに GraphQLは非常に高機能なツールである一方、万能が故に本来必要でないケースでも気軽に利用されている印象を受けます。 筆者は同じ組織で同じ目的のために構築されたサーバとクライアントの通信において、GraphQLを採用すべきでないと考えており、本記事ではそのポイントを整理していきます。 なお、本記事ではこのような1対1型のシステムをサーバクライアント型とよびます。 念のために記載しますが、GraphQLは素晴らしい技術であり、本記事はGraphQLを批判するものではありません。 TL;DR (本当の意

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

はじめに GraphQLを使う中で、Fragment Colocationという手法があることを知りました。 実際に使ってみて Fragment Colocation を利用することでの利点が見えてきたので、記事にまとめようと思います。 GraphQL の Fragment とは GraphQL には Fragment という機能があります。 Fragment はクエリのフィールドをまとめ、再利用可能にします。 Fragment を使うと何が嬉しいのか 再利用が可能になることで、繰り返し記述することを避けられる 繰り返し処理を Fragment としてまとめることで見通しが良くなる 仮にフィールド名が変更になったときに複数箇所変更する必要がなくなる Fragment の実用例

はじめに 前回の記事では、GraphQLについて軽く触れましたが、その時の理解は浅かったため、今回は深めることを目的として、GraphQLの構文をまとめてみました。 スキーマ GraphQLのスキーマは、サーバーがクライアントに提供するデータ構造とAPIの操作を定義します。ここでは、スキーマ定義の基本的な構成要素を見ていきます。 Type TypeはGraphQLの核となる部分です。データの形状を定義し、クエリやミューテーションで扱うオブジェクトの「設計図」となります。 上記のBookタイプでは、idとtitleフィールドが非Nullであることが!によって指定されています。これは、これらのフィールドがクエリの結果に必ず含まれるべきであることを意味します。一方で、authorフィールドには!が付いていないため、このフィールドはnullを許容します。つまり、authorフィールドが値を持たない

FastAPIの公式ドキュメントには、GraphQLのライブラリが紹介されています。 そこでおすすめのGraphQLのライブラリとして紹介されているのが、Strawberryです。 今回はStarawberryのライブラリを使ってGraphQLのAPIを実装しているときに、ログ出力で苦労したことがあったので、何が問題なのかとその解決方法を書きます。 Strawberryについて 改めてStrawberryとはPython用のGraphQLライブラリです。Python用のGraphQLのライブラリはGrapheneが古くからあるライブラリでドキュメントを豊富です。対してStrawberryは比較的新しいライブラリです。 FastAPIのドキュメントには、Strawberryを使用することをお勧めしています。 FastAPIとの設計思想が似ているらしいです。 Strawberryはまだまだ開発

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? SupabaseではSQLだけでなく、GraphQLを利用したデータ取得も行うことができます。 今回はGraphQLでデータを取得して、添付画像のような集計アプリを作ってみます。 Supabaseの準備 ①：Supabaseプロジェクトの作成 Supabaseにログイン（登録していないければアカウント登録から）して、 トップページの「New Project」を押します。 すると、下記の様な画面が表示されます。 適当なプロジェクト名とデータベースのパスワードを入れて新しいプロジェクトを作成しましょう。 ※Regionはできれば自分の住んで

ある機会がありHasuraというものを知りました Prismaチームが開発したPlaygroudは使用した経験があるので、Hasuraとどんな違いがあるのか調べてみたらPlaygroudより使いやすく開発工数をガンガン削減出来るなと感じました！ なので、もしこの記事を読んでHasuraのことを知ってもらえればと幸いです Hasuraについて 簡単に言うとGraphQLサーバーになります Hasuraはテーブルを追跡することでCRUDや集計用Queryなどを自動的に用意してくれる優れものです また、他の自前で用意したGraphQLサーバーとHasuraを統合してリクエストをHasura一つにお任せすることも可能です 単純なCRUDや集計はHasuraに任せて、ビジネスロジックを含むような処理は自前で用意したGraphQLサーバーに任せることで工数の削減に繋げられるかと思います Hasuraに

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? はじめに フロントエンド開発でGraphQLを使っているプロジェクトは多いと思いますが、以前はFragmentで定義された部分の型定義の方法がわからず、型アサーションを使用して無理やり型定義していました。しかし、GraphQLにはuseFragmentという機能があり、これを使うことで、型アサーションを用いるよりもずっと型安全にデータの型を定義できます。なので今回はuseFragmentについて記述していきます。 そもそもuseFragmentとは useFragmentは、Reactアプリケーション内でGraphQLフラグメントを効果

はじめに GraphQLというものをなんとなく知っていたものの、ちゃんと理解できてなかったなと思い 今回簡単な実装を交えて勉強しました。 GraphQLってなに？ GraphQLは、Web APIのためのクエリ言語であり、データ操作と取得のためのランタイムです。 Facebookによって2015年に開発され、以降、データを効率的に取得する方法として急速に普及しています。 GraphQLの主な特徴は、クライアントが必要とするデータの形をクエリで明確に指定できる点にあります。 これにより、過剰または不足なデータの取得を避け、アプリケーションのパフォーマンスを最適化できます。 Restとの違いは？ 下記の違いがあります。 特徴 GraphQL REST

はじめに 既存のシステムでGraphQLを触っているのですが、スキーマを一から作成した経験がないことと、スキーマと型システムの基礎的な部分の理解が浅いなぁと感じていたので学び直しました。 学習方法としては、具体的な題材を元にスキーマを作っていくと知識が定着しやすかったので、その過程も含め、スキーマと型システムの基礎的な内容を共有しようと思います。 本記事の題材と作成するもの 本記事では、ピザとパスタの2種類の商品を提供するオンラインデリバリーサービスを題材にし、2つの商品情報をCRUDするためのGraphQL APIの仕様（スキーマ）を作っていきます。 前提情報 最初にGraphQLのスキーマと型システムについてざっくり説明します。 GraphQLのスキーマとは？ 前述の通り、Graphql APIの仕様を定義するものです。 具体的には、GraphQL APIがどのようなデータを持っており

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? はじめに GraphQLとはBFF(backend for frontend)とはなんぞやということで、触ってみました。 今回作成したものこちら とんでもなく参考にした記事 そもそもGraphQLとは？ GraphQLは、Facebookによって開発されたデータクエリ言語および実行環境です。RESTful APIの代替として設計され、クライアントが必要とするデータを効率的に取得できるようにします。REST APIとは異なり、GraphQLではクライアントが必要なデータの構造とフィールドを明確に指定できます。 メリット 柔軟性: クライア

GraphQL 今回は業務の中でGraphQLを使用する機会があったので、簡単にまとめてみました！ 記事のターゲット graphql_codegenを使ってみたい人 GraphQLの基礎を学びたい人 この記事に記載されていないこと Fragmentについて（今後の記事で扱うかも） 自動生成を行わないで実装する方法 GraphQLとは GraphQLとは、APIを作成し、クライアントがサーバーからデータを取得するためのクエリ言語です。簡単に言えば、クライアントとサーバー間でデータを効率的にやり取りする方法です。 GraphQLとREST APIの違い GraphQLとよく比較されるのがREST APIです。REST APIとGraphQLの主な違いは以下の通りです。 特徴 REST API GraphQL

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

バックエンドにあるREST APIからデータを取得して、GraphQLのスキーマに載せて返すようなBFF（Backend for Frontend）を設計しています。 その過程で、GraphQLでN+1問題を回避するにはどうしたらいいか？という課題に直面したので、今回はその解決策をまとめてみます。 N+1問題とは何か まず、N+1問題とは何かという話から始めます。 例えば、データベース上にAuthor（著者）テーブルとBook（本）テーブルが存在し、関連は次のようであるとします。 今回は「著者の一覧を、各著者に紐づく本の情報とともに取得できるようにしてほしい」というクライアントからの要件を受けて、次のようなGraphQLのスキーマを定義しました。 type Query { """著者一覧取得""" authors: [Author!]! } type Author { books: [Bo

API のバージョン管理 疎結合なシステムにはバージョン管理が必要です。バージョン管理により、クライアント側のシステムやプログラム更新などを考慮せずに、API を改修することができます パフォーマンスを意識する 単に API を実行すると、リソースの取得をはじめとしたコストがかかります。以下の点を意識すると、パフォーマンスを落とさずに作成することができます キャッシュの活用 データ圧縮 パラメータは最小限（簡潔なパラメータ設定） 非同期処理 データ分割 また、日々パフォーマンスを監視して、重い処理がないかを視ることも重要です GraphQL とは GraphQL は、API を開発するためのクエリ言語、ランタイムの一種です。Meta（旧 Facebook）社によって 2015 年頃に公開されました。 GraphQL は、REST の課題を解決するために生まれたもので、以下の要素によって構成

こんにちは。@masatomix です。 最近、現場でGraphQLとRESTサーバを構築する機会があったので、そのとき得られたナレッジを備忘としてまとめておこうと思います。 TL;DR RESTサーバとGraphQLサーバを構築します EntityとRepositoryから RESTサービスを自動生成します(Spring Data RESTの機能) EntityからDDLを実行してテーブルの作成、データ投入を行います(SpringBootとJPAの機能) JPAとSpring Data RESTの機能を使って ManyToOneの関連があるRESTサービスを自動生成します Swggger(OpenAPI)を有効にします。API仕様書のJSONもダウンロード出来ます openapi-generator をつかってRESTにアクセスするプロキシ(TypeScript)を自動生成します Apo

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

はじめに API仕様書を作成する手段としてよく使われるものに、以下があると思います。 API Blueprint + aglio Swagger redocly Excel PDF 昨年「API Blueprint + aglio」で作られたAPI仕様書をredoclyで作り直しました。 作り直した理由は以下です。 「API Blueprint + aglio」の仕様書の記法が好きではなかった YAMLを使ったAPI仕様書がイケイケな雰囲気になっている 「API Blueprint + aglio」の場合は、API仕様書を作成して終わり 「リクエストパラメタ一覧を書く + JSONのサンプルを書く」という手間が煩わしい 作り直す中で、便利だった機能なので紹介しようと思います。 この記事を見てredoclyを選択するきっかけになっていただけたらと思います。 注意 この記事では redocly

はじめに Web APIサービスに対応したクライアントライブラリ開発を手助けしてくれる OpenAPI Generator について調べてみた。 ※ ここでは言語対象を「Python」として記載する。 Swagger CodeGenとの違い 同じくOpenAPI Specificationを使ってコード生成するツールとして Swagger CodeGen もある。 Swagger CodeGenはSMARTBEAR社によってサポートされているプロジェクト。 OpenAPI Generatorは、2018年にSwagger CodeGenからフォークして始まった開発コミュニティ主体のプロジェクト。 誕生経緯は以下で語られている。 https://speakerdeck.com/akihito_nakano/gunmaweb34 Swagger CodeGenは現在もメンテナンスはされているが

これはOrvalの作者自身がswagger codegenといった他の自動生成ライブラリに物足りなさを感じ、特定の技術の上で最適なコード生成をしたいというモチベーションが根底にあります。 Orvalとは？ 改めてOrvalはOpenAPIからclientコードを自動生成するライブラリです。（公式によると）その特徴は、大きく3つ挙げられます。 Productivity Save time to drink a 🍺, get your api ready out of the box in a few seconds. Prevent human error, be sure on the return result by imposing standard formatting. ビールを飲む時間も与えないほど早く、数秒にしてAPI処理のコードを自動生成します！また、標準的な形式を適用する

概要 OpenAPI Specificationの記載ルールの基本的な部分をまとめる。 必須のルートオブジェクト部分だけ深堀りして記載する。 OpenAPIドキュメントについて OpenAPIドキュメントの記載はプロジェクトによって固有のルールがあるっぽいので郷に入っては郷に従うほうがいいと思う。 OpenAPIドキュメントそのものも、「1リクエストにつき1ファイル」のこともあれば「関連するリクエストは1ファイルにまとめる（ユーザー系は1ファイルにまとめる）」等のルールが有ると思う ルートオブジェクトについて openapi, info, pathsのルートオブジェクトは必須となる。とりあえずこの3オブジェクトが記載されていればOpenAPIの仕様書として成り立つ。 記載のセオリーとしてはできるだけcomponentsオブジェクトにpathsオブジェクトとsecurityオブジェクトで使用

from django.urls import path from drf_spectacular.views import ( SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView, ) urlpatterns = [ path("admin/", admin.site.urls), # 127.0.0.1/8000/api/schema にアクセスするとテキストファイルをダウンロードできます path("api/schema/", SpectacularAPIView.as_view(), name="schema"), # SwaggerUIの設定 # 今回は127.0.0.1/8000/api/docs にアクセスするとSwaggerUIが表示されるよう設定します path( "api/docs/", Sp

Swaggerを使用してAPIの仕様書を作成する際、Swagger EditorやStoplight Studioを使用する選択肢などが考えられます。 新規APIの場合はそれらを使用し０から作成する必要がありますが、既存APIの場合Swagger Inspectorを使用することである程度の仕様を反映させた仕様書を自動生成することができます。 現在の業務で「SwaggerHubを使用した既存APIのドキュメント化」を行う必要があるのですが、「１からすべて作成していくのが面倒・・・」と思い探していたところこちらのツールを発見し、試してみました。 【注意】APIの公開設定について 今回はSwaggerHubの無料プランを使用していますが、APIの公開設定はPublicしか選択することができません。 Privateを選択するにはTeamプラン以上を登録する必要があるため、注意が必要です。 既存A

会社で「SwaggerHubを導入するから」と担当を任され、 既存のAPIにOpenAPIを導入する方法を検討中のtenryuです。 多くのOpenAPI導入記事で作成した仕様書とAPIに相違が発生しないようテストが実施されており、 弊社のSwaggerHub導入でも必須だと感じました。 私の担当プロジェクトでは、APIの実装にPHPフレームワークのLaravelが使用されています。 「Laravelで実装したAPI」と「仕様書」に相違が無いことを確認するため, openapi-psr7-validatorというライブラリを利用しテストしている記事がいくつかありました。 しかし、わかりにくい部分が多々あったり、そもそも情報量が少なかったのでまとめたいと思います。 openapi-psr7-validator How To Validateでいきなり躓く 使い方がよくわからない・・・ Ser

/* tslint:disable */ /* eslint-disable */ //DO NOT EDIT MANUALLY import { object, string, number, date, array, bool } from 'yup'; export const LightingSummary = object({ zones: array().of(object({ id: string().optional(), name: string().optional(), deviceId: number().integer().optional(), deviceType: string().optional(), zone: string().optional(), })).optional(), zoneStatus: array().of(object({ id

背景 先日、とある開発にてWebAPIを複数作成することとなり、APIの単体テストやサブシステム間のテストをどのように進めるか考えていた際に、モックサーバーというものをご教示いただいたことで、その後のテストが大変捗ったため、個人の記録として書き記すものです。 先人たちの知恵をお借りするなどして解決できたことを、この場をお借りして感謝するとともに、大変恐縮ですが自分のメモとして、こちらへまとめておきます。 OpenAPI(Swagger)とは API構造を記述するインターフェース記述言語です。yamlもしくはjsonで記述することで、綺麗なAPIドキュメントを作成することができたり、この記事で紹介するようにモックサーバを建てることができます。 https://swagger.io/ https://swagger.io/tools/swagger-ui/ https://swagger.io

やりたかったこと Svelte公式チュートリアルのfetch(uri)の代わりに、 OpenAPI定義から自動生成した型定義されたTypescriptコードを使ってバックエンドと通信したい タイトルに書いてしまったけどスキーマ駆動という語が妥当なのかはよくわからない... 調べ方が悪いのかやろうとする人にとっては当然の内容なのか、調べても出てこなかったので備忘録として やったこと 公式チュートリアルを一通り眺めた状況からスタート SvelteKitの準備 API定義からコード生成 実装 SvelteKitの準備 viteってビルドツールが全部やってくれた(全部Yes) > yarn create vite √ Project name: ... sample √ Select a framework: » Svelte √ Select a variant: » SvelteKit ↗ √

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

はじめに FastAPI は、WebAPI を構築するためのモダンなWebフレームワークです。 類似したフレームワークに、Django(Rest framework)やFlaskがありますが、大きな特徴として、コードからOpenAPIに準拠したAPIドキュメントを自動生成できることが挙げられます。/docsや/redoc、/openapi.jsonで見れるやつです。 ただ、自動生成されるドキュメントを保存する方法についてあまり日本語の情報が見つからなかったのでまとめておきます。 (フロントエンドとバックエンドで分かれて開発を行なっていて、APIの仕様だけ決めてドキュメントをGitHubPagesなどで共有、それを元にそれぞれ作業を進めたい時などに便利かと思います。) openapi()メソッドを利用してhtmlを生成する FastAPIにはopenapiスキーマを返すopenapi()メソ

はじめに いくつかのプロジェクトにてSwaggerを利用した、API仕様書の運用をしています。 エンドポイントの追加・変更などがあった場合に、ドキュメントの更新を忘れがちなので、github上でPRを作成した際に、swaggerドキュメント生成のためのコマンドを自動実行し、差分があった場合はPR上にコメントするようなフローを作成しました。 使用言語及びライブラリは以下。 https://github.com/swaggo/gin-swagger 前提として、DockerfileやMakefile等でSwaggerドキュメントの生成ができている状態とします。 (各種ライブラリなどで設定方法・実行方法は違うと思うので、Swaggerの設定部分については割愛します。) 実行ファイル 全体の設定ファイルです。以下で一つ一つ見ていきます。 PRのオープン・プッシュのイベントでトリガーされます。 na

type AnyOf<T extends any[]> = T extends [infer A, ...infer B] ? A | AnyOf<B> | (A & AnyOf<B>) : never; JSON Schema とは JSON Schema というものを聞いたことがあるでしょうか。 詳細は https://json-schema.org/ を読んでいただければと思いますが、簡単に説明すると JSON をバリデーションする (または 型をつける)もので身近なところでは OpenAPI などのレスポンス型定義などに用いられます。 他にも各種設定ファイルで JSON や YAML を書くときにテキストエディタ上で補完が効くものは内部的に JSON Schema が使われていることがほとんどだと思います。 例: { "type": "object", "properties":

redoc on Docusaurusがしたいと思ったことが結構あります。 理由は単純で、Github PagesでDocusaurus製のドキュメントを作ってさらにRedocを置くとなると場所が足りないからです。 なんか頑張ればサブディレクトリとかでどうにかできなくもなさそうな気がするんですが、仮にできてもそれぞれのドキュメントをまたぐ際などに手間がかかるのであまりスマートではない気がします。 なので、Docusaurus上でいい感じにOpenAPIのファイルを表示してくれるプラグインかなにかはないかと探していました。 そんな中で見つけたのが、redocusaurusです。もう直球ですね。 redocusaurusを試す これです 以下のコマンドを実行します。 presets: [ // Redocusaurus config [ "redocusaurus", { // Plugin

はじめに こんにちは、rendaman0215です。 APIの設計のフェーズでGoogleの記事で以下のような記事を読みました。 とてもわかりやすかったので、良い機会のためまとめてみようと思います。 HTTP通信3つの主要な方法 記事内では、以下の3つが主要な方法として紹介されています。 REST gRPC OpenAPI これが主題になるのですが、gRPCはさておき、そもそもOpenAPIはRESTを記述するフォーマットなので比較対象にならないのでは？？と思いました。 よくよく読み進めてみると、記事内でOpenAPIと言われているものは、RESTに関わらずRPCのような使い方を指しているように見受けられました。 REST RESTと呼ばれる以下の4つの定義に合致するもの 状態管理を行わず、やり取りされる情報のそれ自体で完結して解釈することができる 情報を操作する命令の体系があらかじめ定義

これは株式会社LabBase テックカレンダー Advent Calendar 2022 4日目の記事です。 株式会社LabBaseでエンジニアをしている高橋です。 昨日の記事は @yiwi さんによるRust学習の試行錯誤の記事でした。(こちら) 今回はOpenAPI Generatorで生成したコードRustのコードを、検証プロダクトの本場環境利用するまでに行ったことについて紹介します。 TL;DR rust-serverでサポートしてない機能に対して、自力で実装して乗り切った OSSを使う際は自己責任で OpenAPI GeneratorのRust言語サポートについて OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and

概要 既存のLaravelプロジェクトへSwaggerを導入するにあたり、「Laravel API Documentation Generator」なる便利パッケージでSwaggerのyamlを自動生成できることを知りました。 しかし、インストールを試みたところ↓のエラーが発生しインストールできませんでした。 Your requirements could not be resolved to an installable set of packages. Problem 1 - mpociot/laravel-apidoc-generator v4.x-dev requires ramsey/uuid ^3.8 -> found ramsey/uuid[3.8.0, ..., 3.x-dev] but the package is fixed to 4.2.1 (lock file ve

はじめに この記事はOPENLOGI Advent Calendar 20227日目の記事です！ 私事ですが2022/12月にオープンロジにジョインしました！頑張ります！ まだ入社して間もないので業務にあまり関われてないのですが個人的に最近やったことを紹介させていただきます！ 開発にコミットするAPIドキュメントを作る 皆さんの現場ではAPIドキュメントは開発にコミットしていますか？ 開発にコミットしていないAPIドキュメントの例として、 Swaggerを誰かが作ったけどメンテナンスされていない メンテナンスしているけど誰も見ていない メンテナンスしているけど信頼性が担保されていないので使えない みたいな状態になっていませんか？ APIドキュメントを書くと何がいいの？ APIドキュメントって何に使うの？と思うエンジニアも意外と多いのではないでしょうか 実際SwaggerやStoplight

これは株式会社LabBase テックカレンダー Advent Calendar 2022 8日目の記事です。昨日の記事はこちらです。 今回はutoipaを使って、Rustで実装したAPIを確認できるようにします。 TL;DR utoipaをcloneする。 examplesディレクトリにある好きな環境で、cargo run実行する。 http://localhost:8080/swagger-uiへアクセスする。 Swagger UIでAPIが確認できる。 はじめに Rustで作ったバックエンドのAPIドキュメントを作成するために、Rustだけでどうにかならないかなと検索したら、utoipaというライブラリで解決できそうだったので、組み込んでSwagger UIで確認してみました。 がんばればOpenAPI Generatorが生成したコードを使えるようです（参考記事） utoipaとは

OpenAPIで使うな危険を示したいときのtips 例えばこんな時 APIを削除・追加したいのでOpenAPIを修正しなければいけない OpenAPIで仕様共有をしているけど、一部のAPIを近い将来に廃止したい APIのパス設計を見直したので、古いパスのほうは使わないようにしてほしい 例：/user_profile/xxx -> /user/profile/xxx OpenAPIで使うな危険を示す方法 deprecated=true に設定する（OpenAPI Specification） ポイント 要らなくなったソースコードをごそっと削除するのとは違い、現在使われているAPIの場合、 丸ごと定義を削除してしまうと「あれ？あのIF仕様どこいった？？」と思われてしまう しばらくの期間deprecatedの状態で置いておき、全体への周知が終わってから削除するべき

はじめに こんにちは。READYFOR のプロダクトエンジニアのもっさんです。 この記事は「READYFOR Advent Calendar 2022」の 12 日目の記事です。 概要 READYFORでの機能開発 READYFOR では、新規・追加開発を行う際、スキーマ駆動開発を利用して開発を進めています。 スキーマの定義には OpenAPI を利用していて、定義の yaml ファイルをメンバーで相談しながら作成後、その定義を元にフロントエンドとバックエンド分かれて実装を進めています。 フロントエンド領域でのスキーマ利用 フロントエンドでは TypeScript で開発をおこなっているので、この定義をもとに型定義ファイルを作成、実装を行なっています。 READYFOR のフロントエンドでは、SPA またはマイクロフロントエンドがコンテキストごとにいくつか分かれて存在しています（SPA ま

この記事は ドワンゴ Advent Calendar 2022 11 日目の記事です。1日遅刻してしまいました こんにちは、@tasuwo です。普段はニコニコ動画 iOS アプリの開発に携わっています。ニコニコ動画iOSアプリ (以下、動画iOSアプリ) では3年程前から OpenAPI 仕様を元に APIクライアントを自動生成し、動画iOSアプリとボカコレアプリで利用しています。その中で得られた知見について紹介しようと思います。(そもそも OpenAPI とは？という話は、今回は割愛します ) コード自動生成導入の経緯 主なモチベーションはやはり省力化でした。導入以前は仕様書を元に実装を行い、同じ仕様書を元にレビューするといった工程が必要でしたが、仕様書からコードが自動生成できれば多くの手間を省くことができます。 また、動画iOSアプリから主に利用するAPIでは既にOpenAPI仕様が

この記事は 株式会社ビットキー Advent Calendar 2022 14日目の記事です。 今回は workhubプロダクトチームの maruware が担当します。 背景 BitkeyではOpen APIを以下のような用途で活用しています。 API仕様、ドキュメント 自社製のジェネレータによるサーバー実装やクライアント実装生成 サブシステムのモックサーバー Open APIに則ることで、1のメリットはもちろん、2によりサーバー実装で統一的なアーキテクチャ・validation・テストなどを得られたり、テストサーバー・クライアント間で整合した実装を得られたりといったメリットがあります。 しかし、残念ながら提供しているAPIはすべてがOpen APIで定義されている状態にはなっておらず、それらについてもOpen APIに載せていく移行を進めています。 その移行作業やジェネレータ整備などを

openapi: 3.0.0 info: title: OpenAPI example description: "OpenAPI example" version: 1.0.0 servers: - url: https://example.com/api/v1 paths: /user/{username}: get: operationId: getUserByName summary: Get user by user name parameters: - name: username in: path required: true schema: type: string responses: "200": description: successful operation content: application/json: schema: $ref: '#/component

はじめに Railsで運用されているAPIサーバーのシリアライザとSwaggerスキーマをリファクタリングした話と、そこで当たった問題(余談)の紹介です。 現状の状態 社内のサービスはAPIサーバーとしてRailsを用いて運用されているのですが、長く運用されているため、手動で作成されるSwaggerスキーマとそれに対応したシリアライザが無秩序な状態にあり、新規APIの実装や修正が入るたびに各人の裁量でスキーマおよびシリアライザを使用・作成していて、運用しづらくなっていました。また、ActiveModel::Serializerなどは使っていなく、独自で実装を行なっています。 実際にどのような構成になっていたかの例を大雑把に。 例 例えば、以下のようなモデルがあったとして class Member < ActiveRecord::Migration def change create_tab

はじめに 今回は Go 言語で OpenAPI のコード自動生成を試してみたいと思います。「コード自動生成って何だ？」という方や「OpenAPI ってそもそも何？」という方にもわかりやすく解説していこうと思います。 まず、OpenAPI でコード自動生成ができると以下の嬉しいことがあります。 ただの作業になりがちなモデルの作成が自動化できる 仕様書通りにモデルや API インターフェースが自動生成されるので、バグが入りにくい 仕様書通りのリクエスト・レスポンスかどうかを簡単にバリデーションできる その結果、ビジネスロジックに集中する開発ができる です。 今回のサンプルコードはこちらに置いてあります。 OpenAPI とは OpenAPI とは、 REST API の定義を記述する仕様のことです。例えば、以下は「GET /users API を叩いたら200ステータスで　id, name を

どんな内容か CDKにてAPIGateway+Lambdaの構成を作る際に、RestApiではなくOpenAPI定義からAPIGatewayを作ることができるSpecRestApiを使ってみたという内容になります。 OpenAPIとは OpenAPIとは、RESTful APIを記述するための標準化されたフォーマットのことで、OpenAPI Specification(OAS)やOpenAPI Generatorなど取り巻く技術の総称としても呼ばれています。 もともとswaggerとして有名だったのですが、OASとして標準化されてからはOpenAPIと呼ばれることが多く、swaggerはOpenAPIのツール的な位置付けになっています。 例えば、https://jsonplaceholder.typicode.com/ というRESTfulAPIを公開しているサービスがあるのですが、その中

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? はじめに こんにちは！株式会社80&Companyの技術広報です。 弊社の開発部署では毎週火曜日の朝9:30から社内勉強会を行なっています。 今回の記事は社内のエンジニアがフロントエンド業務を担当していた際に、API周りの作業改善のため、スキーマ駆動開発の導入提案を社内勉強会で発表したものを紹介します。 スキーマ駆動開発を検討中の方は参考にしてみて下さい♪ 読者の対象 スキーマ駆動開発に興味がある方 スキーマ駆動開発の導入を検討している方 スキーマ駆動開発とは スキーマ駆動開発とはAPIのスキーマを最初に定義して、定義をもとにバックエン

みなさんはSwagger Editor等で作成したAPI仕様書と実装の乖離をどのようにテストしていますか？ 多くの記事で目にするのは、openapi-psr7-validatorというライブラリです。 こちらはPSR-7に準拠したバリデータを使用するため、リクエストとレスポンスもPSR-7仕様に変換するという、少し面倒な工程が必要となります。 もう少し手軽にテストができるライブラリがないか探していたところ、こちらのSpectatorというライブラリを見つけました。 こちらもリクエストとレスポンスの型をテストできるらしく、試しに使ってみたのですが・・・という記事になります。 環境 PHP 8.0.8 Laravel Framework 8.58.0 Spectator v1.7.1 仕様書の保存場所に注意 今回OpenAPI Specのyamlをapp/OpenApiの中に保存しました。 そ

AWS CloudFormation と OpenAPI を使用して Amazon API Gateway を構築する時、「デフォルトのエンドポイント」を無効にする方法がわかりづらかったので、ノウハウを残します。 AWS SAM の AWS::Serverless::API リソースには、デフォルトのエンドポイントの有効と無効を切り替える DisableExecuteApiEndpoint プロパティがあります。 しかし、AWS CloudFormation テンプレートで OpenAPI を DefinitionUri 使用して設定している場合（調査中）、DisableExecuteApiEndpoint プロパティが効きません。 従って、AWS の OpenAPI 拡張を使用し、AWS CloudFormation テンプレートではなく、OpenAPI 内に設定を定義する必要があります

開発している家計簿アプリSUMUMAのAPIとAPIドキュメントを公開しました。 ドキュメントはSwaggerとRedocの2種類で公開しています。 Swagger SUMUMA API Redoc SUMUMA API APIとドキュメントの公開には、Django Rest Frameworkとdrf-yasgを使いました。 Django Rest Framework Django Rest Framework（以下DRFで表記）は、DjangoアプリでAPIを提供するためのパッケージです。DjangoでAPIを実装するときに、必ずと言っていいほど使われています。 DRFはOpenAPIという、RESTful APIを定義するためのフォーマットをサポートしています。OpenAPIを元にAPIドキュメントを生成することもできます。 DRFのドキュメントには、パッケージを使わずにAPIドキュ

OpenAPI定義からAPIGatewayをいい感じに作成できたので、伝えたかった記録になっています。 どんな流れで 「OpenAPI ×CDK」 に辿り着いたのか、つらつら書いています。 長い記事になっていますが、本当に伝えたいのは最後のCDKの話だけです！ 時間が勿体ない方は最後の方だけ読んでいただけたらと思います。 【想定している層】 APIGateway そこそこ分かる CDK 聞いたことある OpenAPI(Swagger) 聞いたことない 【私のレベル】 APIGateway 2年くらい使っているけど未だにCorsエラーとかで沼る。 CDK 1ヶ月前くらいから触り始めたけど、既に好き。CloudFormationに戻れない。 OpenAPI 『スキーマ駆動開発』、とかの記事をみて気になっていて、最近初めて実際に触った。 OpenAPIとは？ 「Restful APIの定義を記述

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

リクエストをカスタマイズしつつOpen APIの定義ファイルからSWRフックを生成する方法をメモがてら記載する。 リクエストをカスタマイズしたい需要としては、APIエンドポイントに認証など追加の手続きが必要な処理が存在する場合に、その手続きを実施するためのカスタマイズを行うなどである。 Orvalの選定理由 Open APIからコードを生成するツールは多々あり、選定が難しい。最終的に残った候補のみを記載する。 Orval 設定ファイルが単純かつ、ドキュメントがしっかり書かれている。カスタマイズもある程度柔軟に可能。生成されるコードが比較的シンプルでわかりやすい。 swagger-typescript-api ejsを利用したテンプレートを利用し柔軟にカスタマイズできるため複雑なケースには有用だが、ejsは読みにくく開発難度が高い。(別プロジェクトで導入実績があるため、Orvalで実現できな

OpenAPIとは OpenAPI（旧称Swagger）は、RESTful APIの定義とドキュメント化のための仕様です。この仕様を使用して、APIのエンドポイントやリクエスト・レスポンスのフォーマットをJSONまたはYAMLで記述します。OpenAPIを用いることで、開発者はAPIの仕様をチーム内でスムーズに共有することができ、さらにツールを利用することで型定義などのコードを自動生成することができます。 OpenAPIでAPIの仕様を記述した例 openapi: 3.0.3 info: title: Sample API version: 1.0.0 servers: - url: "http://localhost:8080" description: "ローカル環境" - url: "http://sample.com" description: "本番環境" tags: - nam

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

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

openapi: '3.0.3' info: title: SwitchBot version: "0.0.1" servers: - url: https://api.switch-bot.com/v1.0 security: - Authorization: [] paths: /devices: get: operationId: devicesget responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/Devices" /devices/{deviceId}/status: get: operationId: devicesidstatusget parameters: - name: deviceId in: path required: tr

今回は、swaggerを使って開発効率を爆上げしたいあなたに、ちょっと踏み込んだswagger活用術を紹介したいと思います！ paths sectionを修正しなければいけない機会を最大限少なくする paths sectionってそもそも指定すべきプロパティが多いので、ちゃんとAPI仕様を作ろうと思うとどうしても見づらくなります 特に、parametersやrequestBody、responsesが同居すると記述のルールが違うので統一感がなく、階層が深くなり見づらいです そんなpathsはやはり最大限シンプルに保つべきというのが運用していて思うことです 以下にpathsを最大限シンプルに記述した例を提示しますので、是非参考にしてみてはいかがでしょうか！ openapi: 3.0.3 servers: - url: http://localhost:3000 info: title: te

こんにちは zane です。 Collections というオープンソースのヘッドレス CMS をつくっています。今回パブリックな API 仕様書が必要になり Next.js(Nextra) + Redoc という組み合わせを試したら、なかなか良かったので手順としてまとめてみました。 OpenAPI(Swagger)などを使った API 仕様書はだいたいどのプロジェクトでも作成しますが、それを公開するとなると、機会はあまり多くはないかもしれません。が、大きく技術トレンドが変わる分野でもないので、覚えておくといずれ役に立つかもしれません！ 完成品 公開されているページはこちら コードはすべて GitHub で公開していますので、参考にしてみてください。 https://github.com/collectionscms/collections/blob/main/docs/pages/ref

はじめに こんにちは、kenです。 先日、システム内で異なる権限を持つユーザーに対して、一部叩けるAPIに制限をかける必要がありました。その際OpenAPIのyamlに書かれる「Tags」機能を使うことでこの問題を解決したので、本記事ではこの方法の詳細と実際の実装サンプルをご紹介したいと思います。これは比較的簡単で、かつメンテナンスが容易な方法だと思います。 本記事はHRBrain Advent Calendar 2023の14日目の記事です。 経緯 経緯については差し障りがないよう一部情報をぼかして書きますが、先日業務の中で「とある条件Aを満たしているユーザーについては一部のAPIを叩けないようにする」という対応をする必要がありました。 身近な例で例えると、一般会員とプレミアム会員のように会員の中でグレードがあるようなシステム体系のなかで、プレミアム会員にだけ許されているAPIを一般会員

この記事はカバー株式会社 Advent Calendar 2023 15日目の記事になります。 カバー株式会社エンジニアのSです。よろしくお願いいたします。 前回の記事は @ys-cover による「カバー株式会社におけるAWS Control Towerの導入」でした。AWS Control Tower の導入を検討されている方にとって、とても興味深い内容となっておりますので、こちらの記事もぜひご覧ください。 はじめに 先日弊チームメンバーが作成した記事が公開されました。記事に対する反応で多かったのが API クライアントの自動生成の箇所でした。 API クライアントの自動生成には openapi-generator の dart モジュールを利用しています。早期に API クライアント自動生成の仕組みを整えることで、クライアントチームは本質的な機能実装に注力可能になりました。 また A

はじめに NRI OpenStandia Advent Calendar 2023の 20日目担当のあやかです。 フロントエンドのバリデーション定義ファイルを自動生成出来ないか試してみたので紹介します この記事の前提として、 バリデーションライブラリとして、TypeScript first でスキーマ定義とバリデーション設定を行うことが出来るZodを使用 OpenAPI Specification（以下OAS）とJSON Schemaからファイル生成出来るかを検証 手動でバリデーション定義をしたファイルと自動生成したファイルの両方のバリデーションチェックを適用出来るか検証 を行い、その結果を紹介する記事です。 背景 業務でとあるWebアプリを開発しています。 このアプリは入力項目がとても多く、フロントエンドでもバックエンドでもバリデーションをかけなければいけないという要件があります。 そう

この記事は mediba Advent カレンダー2023 の20日目の記事です。 ※記事の内容はあくまで個人の発信であり、会社を代表する意見や見解ではありません。 ※記事内のコードは実際のプロダクトのものではなく記事用に作成したものです。 この記事ではNode.jsのHTTPサーバフレームワークであるFastifyでのAPI開発で、OpenAPIを使ったスキーマファースト開発を実現した話を書きたいと思います。 はじめに あるプロダクトを短期間で開発する必要があり、FE/BEの開発を並行してスタートできるようにスキーマファーストで開発することにしました。 FE/BEメンバーが集まって、APIのIF定義をOpenAPI Specification v3.0形式のYAML(以下、OpenAPI)で記述しながら決めました。 APIの開発において、フレームワークには前プロダクトを踏襲してFasti

はじめに こんにちは。@komasayukiです。 この記事は、全世界2,800万人以上の開発者に使われているAPIプラットフォームPostmanの記事を書こう by Postman Advent Calendar 2023 の8日目です。 PostmanとChatGPTを組み合わせて、APIサーバーの開発を爆速で行う方法を紹介します。 Qiitaのようなナレッジ共有サービスを作ることを題材としてやってみましょう。 なお、今回使うサービスはすべて無料で利用できます。 ChatGPTを使ってQiitaクローンのOpenAPI仕様を作る OpenAPIとは、APIの仕様を記述するための標準規格です。サーバーがどういうRESTリクエストを受け付けて、レスポンスするかを記述します。 これは重要な作業ですが記述が難しいです。ChatGPTにお願いしましょう。 以下のようなスクリプトを書きました。 あ

初めに 今回はOpenAPIを用いたAPI設計書の書き方とSwagger(UI)の使い方についてまとめていきます。 この記事の目標はタイトルの通り、OpenAPI仕様に則ったAPI定義を作成し、SwaggerからそのAPI仕様を確認できることです。 API設計などについては省いており、あくまでOpenAPI仕様の書き方についての解説記事になります。 OpenAPIとは RESTful APIのインターフェースを記述するためのフォーマットです。 定められたフォーマットに則ってAPIの構造と動作を明確に定義することで 開発者はAPIのエンドポイント、パラメータ、レスポンスなどを正確に文書化し、共有することができます🚀 Swaggerとは Swaggerは、OpenAPI仕様を視覚化し、対話式のAPIドキュメントを提供するための一連のツールです。 以下のようなものがあります。 ツール 概要

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? はじめに 弊社は、ハノイの小さなソフトウェア開発会社だ。あんまり忙しいのは嫌なので、規模は拡大せず、少人数で開発を行っている。私以外は、ベトナム人エンジニアで、スキルはまちまちだ。 受託案件では API を作ることが非常に多い。何度も作るので、なるべく工数がかからないように、なるべく品質が一定になるように作りたい。API に限らず、弊社では、Agile, Assets & Automation という 3 つの戦略で開発を行っている。Agile と Automation はその名の通りで、Assets は、簡単に言えば再利用可能なモジュ

概要 API Gatewayの設定にOpenAPIを連携できないか検討した。 OpenAPIのJSONから型情報を読み込む形で実装してみたメモを残す。 検討 cdk - openapi-definitionを読むと、定義はすべてOpenAPIのほうに書く必要があるもよう。また、OpenAPIは3.1は使えず3.0か2.0を使う必要がある。 すべてのリソースとメソッドは OpenAPI 仕様ファイルの一部として定義する必要があり、CDK を介して追加することはできません。これは、これらのプロパティの重複や潜在的な混乱を防ぐためです。 こちらの記事で「OpenAPI定義にAWS用の設定値を記載するのが嫌だ」と言っているように、OpenAPIとAWSの設定は分けて管理したい。 記事中ではopenapixを使用しているが、1年更新がないのが不安。 型定義をOpenAPIから取り込む方法を考える。

皆さんは、WebアプリのAPI仕様を定義するときはどのような方法をとっているでしょうか。StoplightのようなGUIツールを使うか、それともyamlをそのまま記述するか…。 私は今まで、後者のようにそのまま頑張ってyamlを書いていました。ただ、OpenAPIの文法を覚えなくちゃいけなくって大変だったり、冗長な作業になることもあったりして退屈だなぁーと思っていました。そんな中、この記事の主題であるTypeSpecというものを知って使ってみたので、その内容をこちらにまとめたいと思います。 概要 TypeSpecはMicrosoftが開発をしている、API仕様の定義などに特化した独自言語です。JavaScriptに似た使用感でAPI仕様を記述することができます。また、node.jsのエコシステムでコンパイルまで完結でき、セットアップの手順も少なく簡単でした。 セットアップ コンパイラのダウ

はじめに これは、REST APIの仕様書としてOpenAPI Specification（以下、OAS）を管理していて、そのOASを元にPostmanコレクションを作成・更新したい思っている人向けの記事です。 PostmanはGUIベースのアプリケーションであり、このGUIからOASをインポートして新規のコレクションを作成できます。作成後は、GUIを介してコレクションを直接更新ができます。しかし、この手動でのGUIを通したコレクションの作成・更新だけでなく、自動化したいニーズもあるかと思います。たとえば、GitHubなどのコード管理システムでOASファイルを管理しているシナリオでは、以下のような手順でのコレクションの作成・更新が考えられます： コード管理システム（GitHubなど）で管理しているOASファイルを更新する OASファイルの更新をトリガーにCI/CDワークフロー（GitHub

3-shake Advent Calendar 2022 の 1 日目です。 株式会社スリーシェイクのメンバーが各々自由に技術・非技術ネタを投稿していきます。 1 日目のこの記事では、 Step CI という API テストツールが最高だったので紹介します。 概要 Step CI は API をテストするためのシンプルなオープンソースのコマンドラインツールです。 REST はもちろん、 GraphQL や gRPC などその他様々な種類の API に対応しています。 stepci CLI をインストールして簡単な YAML ファイルを作成するだけで API のテストを実行することができます。 実行イメージ 検証環境 Step CI v2.5.5 Node.js v18.12.1 リポジトリ この記事内で使用しているサンプルコードは以下のリポジトリで管理しています。 使い方 1. インストー

はじめに こんにちは、D2Cのエンジニアの吉田です。 本日は私たちのチームが普段 Web API 開発で実際に利用している Step CI を用いたAPI自動テストの構築例を紹介しようと思います。 Step CI の簡単な使い方や利点をまとめ、CI/CDパイプラインとの統合についてまとめます。 Step CI とは Step CI はオープンソースのAPI自動テストツールです。 言語にとらわれず、YAML形式で簡単にAPIテストを記述することが可能です。 この記事ではRESTベースのAPIテストを紹介しますが、GraphQL、gRPC、tRPC、SOAPといった異なるタイプのAPIテストを1つのワークフローでテストすることができます。 他にもCI/CDに組み込むことも可能で、Github ActionやBitbucket Pipelinesと統合することで継続的に自動テストを実行することが

個人プロジェクトでバックエンドとしてSupabaseを使っている。 SupabaseだとUIをぽちぽちするだけでバックエンドが完成。とても便利だ。 フロントエンドに集中した開発ができる。 今回はSupabaseで設定したバックエンド情報を元にTanStack Queryのエンドポイントメソッドを自動生成してみようと思う。しかし、OpenAPIのドキュメントをいちいち書くのがめんどくさいのでSupabaseさんに生成してもらいたい。 OpenAPIドキュメント生成 公式ドキュメントやGoogleドキュメントで調べてみてもやり方が見つからず、、 ChatGPT先生に聞いてみた。 Supabaseは、自動生成されたAPIドキュメントを提供しています。これを取得するには、以下のURLにアクセスします。 https://YOUR_PROJECT_ID.supabase.co/rest/v1/?api

こんにちは。今回のポストでは、OpenAPI Specification、protobuf、gRPC、avroなど、一般的にインターフェース定義言語 (IDL) と呼ばれるものをPolyglot MSA環境で共有モジュールとして導入した事例について紹介したいと思います。 IDLとは？ 一般的にIDLと呼ばれるgRPCを例に取ると、以下のように「通信」に関する仕様を記述することができます。 通信を仕様化することで共通のコードを通じた通信の共有 IDLによる前方/後方互換性の確保 通信を仕様化することで共通のコードを通じた通信の共有 ほとんどのIDLツールはCodeGenをサポートしています。例えば、上記の例の仕様を作成すると、通信部のオブジェクトとコードがすべて生成されます。これはクライアントとサーバーの両方で使用でき、IDLを作成することで、別途のI/O検証なしに信頼性の高いコードを作成で

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

要約 システムの保守性をあげるために自動テストを書くのは良いアプローチといえる しかし自動テストを書く時間がなかったり書くスキルがないメンバがいるという諸事情はよく発生する そうした時は最初(書き始め)のタイミングで、テスト対象のクラス・メソッドの処理を最後まで処理が通る1ケースだけ書こう このアプローチはシステムの保守性をあげるだけではなく、個人・メンバのスキルアップにも繋がることがある テスト容易性とは テスト容易性をGoogleで調べると難しそうな話が出てきますが、本記事では テストがしやすい というふんわりとした言葉の意味合いで使っていきます テスト容易性はシステムの保守性を支える1要素ともいえ、このテスト容易性を高めることでシステムの保守性を少しでも高めることができるものです。(もちろん銀の弾丸ではありません) 質とスピード by t_wadaさん テスト容易性をあげるアプローチ

RSpecでit / example / specifyはどのように使い分けるのか？〜日本語で書くならexampleって本当？〜RubyRailsRSpec はじめに 最近ときどき「RSpecでit/example/specifyをどのように使い分けたら良いのか」という話題を見かけるので個人的な私見を書いてみます。 使い分けに何か決まりはあるのか？ → 技術上の決まりは何もありません it/example/specifyは技術的にはまったく同じメソッドです。なので、itをexampleやspecifyに置き換えても問題なく動きます。 # itを使う it 'adds numbers' do expect(1 + 1).to eq 2 end # itの代わりにexampleを使う example 'adds numbers' do expect(1 + 1).to eq 2 end # i

cancancanを使った際、テストに学びがあったので投稿します。 前提：cancancanとは 権限による制御が簡単にできるgemです。 cancancan Rails|CanCanCanの使い方解説 ↓私も1つ記事を書きました。 cancancanでモデル名に紐づかない制御をする方法 cancancanのテスト requestスペックなどで特定の権限が各アクションを実行できるかどうかをテストする方法もあると思いますが、今回はcancancanが用意しているmatcherを使ってテストする方法を紹介します。 参考 https://github.com/CanCanCommunity/cancancan/blob/develop/docs/testing.md require "cancan/matchers" describe "User" do describe "abilities"

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

rspec書き方指南ではない 最近自分でやってみて、テストが意外に楽に書けるのではないかと思うやり方をまとめてみた。 ベストだとか唯一の書き方だとかそういう事を言いたいわけではない。各自自分の好きなやり方で書けばいいと思う。最終的には自分の書いたクラスがちゃんとテスト出来ていれば目的は達成している。 個人的な主観としてテストは出来るだけシンプルにしたい。そうじゃないと個人的にテストを書くのが嫌になるし、テストが間違ってて、そもそも何をテストしてるのか？という事になりたくない。 と言うことを解決できるのではないかという投稿。 要点 クラス内のメソッド（処理）は出来るだけシンプルにしたい 一度しか呼ばれないようなロジックでもメソッドに落とし込みたい メソッドが増える分、内部のメソッドと外部向けのメソッドをちゃんと意識する itに説明は要らない テスト中に使用する変数内容は実際の条件を意識しない

はじめに AWS SDKを使用したコードに対してテストを記述したい場合、AWSのSDKで用意されているClientStubsを使用して、スタブを行うことが可能です。 ドキュメント自体は公式が出しているものがありますが、この例だけではやりたいこと（Aws::S3::Client以外のインスタンスを使うケース）が実現できなかったので、今回調べたことについてまとめました。 環境 Ruby: 2.7.1 aws-sdk: 3.1.0 aws-s3-sdk: 1.114.0 公式ドキュメントから このドキュメントにあるようにAws::ClientStubsというモジュールが、各サービスに対応したClientクラスにincludeされています。 今回はS3を使って、その例を紹介します。 このモジュールに定義されているのはapi_requests, stub_data,stub_responsesの３つ

TL;DR RailsのメソッドをRspecでテストする際に、Elasticsearchを使ったモデルに対してのテストの実行時にのみ、実行前後でElasticsearchのインデックスを初期化する処理を入れる方法です。 やりたかったこと elasticsearch-railsgemを用いたRailsのアプリケーションにおいて、下記のようにElascticsearchを用いて検索や絞り込みを行うメソッドを実装しました。 class SampleClass < ApplicationRecord def search(filter_ids, target_ids: [], min_price: nil, max_price: nil, size: 200) __elasticsearch__.search({ size: size, query: build_query(filter_ids,

更新 2023/02/12 rspec-parameterized gemを使用したコードサンプルを追加 完全なコードベースのリンクを追加 Tl;DR テストにおいて、可読性は最重要 一方でDRYに書かないと保守性が悪い場合もある 折衷案として、コメントやインデントを活用するといいかも・・！ rspec-parameterized gemを利用するとより良い 前提 本記事では、言語/テストフレームワークとしてRuby/RSpecを使用します あくまで筆者の主観/経験に基づく一意見であることに留意ください テストにおいて、可読性は最重要 テストにおいて、可読性は最も重要だと考えます。例えば以下のような関数をテストしたい場合、 # 半角数字7桁の文字列かどうかを判定する def self.valid_postcode?(postcode) return false unless postcod

はじめに 本記事は、私が最近読んだ著書 「単体テストの考え方/使い方」で紹介されている、リファクタリングに強いテストを書くためにはどうするべきか、という記述について簡単にまとめたものです。ここで紹介する内容以外にも多くの素晴らしい情報が詰まった本なので、是非皆様も読んでみてください！ リファクタリングへの耐性 まず、本書において作者は、テストの目的とはバグを起こすことなく、新しい機能の追加やリファクタリングを行えるようにすることだと述べています。 そこで、テストコードが備えるべき要件の一つとして、リファクタリングへの耐性を挙げています。 参考：良い単体テストを構成する４本の柱 バグに対する保護 リファクタリングへの耐性 迅速なフィードバック 保守のしやすさ リファクタリングへの耐性とは、テストが失敗することなく、コードのリファクタリングが行えるかどうかを示す指標です。 例えば、リファクタリ

テストの正常系、異常系、準正常系について ソフトウェアテストは正常系、異常系、そして準正常系のケースをカバーすることが重要です。これにより、アプリケーションが予想どおりに動作し、エラーや問題に対処できるかどうかを確認できます。 1. 正常系テスト 正常系テストは、アプリケーションが正常な状態で正しく動作するかどうかを確認します。ユーザーが期待通りの操作を行う場合の挙動をテストします。例えば、ユーザーがログインし、メールを送信するなどです。 2. 異常系テスト 異常系テストは、アプリケーションが異常な状況に遭遇したときにどのように振る舞うかを確認します。ユーザーが誤った情報を提供したり、システムエラーが発生した場合のテストです。これにより、エラーメッセージが正しく表示され、セキュリティの問題やデータ損失を防ぎます。 3. 準正常系テスト 準正常系テストは、正常系と異常系の中間に位置します。一

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

SmartHR Advent Calendar 2023 シリーズ2の1日目です。 最近、あるメソッドに対してテストケースが漏れなく書かれていることを保証するテストがほしいと思うことがあったので調べてみた記録を残します。 どういうときにそのようなテストが欲しくなるか、具体例を見ながら説明していきます。 具体例 ここに2つの数値と演算子となる文字列を渡すと計算結果を返してくれる.calcメソッドを持つCalculatorクラスがあります。 現時点では足し算（plus）、引き算（minus）に対応しています。 class Calculator AVAILABLE_OPERATORS = %w(plus minus)# 足し算、引き算のみできる def self.calc(left, operator, right) raise ArgumentError unless AVAILABLE_OP

発生した問題 私たちが扱うプロダクト内では、ユーザーの入力値に基づき表示が変化する動的なUIが存在します。 このフロントエンドのテストはRSpecを用いて行っていました。 しかし、このような動的UIの自動テストは、何回かに1回の確率で落ちてしまい、GREENになるかどうかがある意味「運次第」となる傾向がありました。 問題が発生することの課題 変更していない箇所に対してテストが落ち、CIツールの画面上で「Retry」をすることは開発スピードの足を引っ張ります。 そこで、落ちやすいテストに関して自動でリトライしてくれるgemを導入しました。 対象となるテスト example '試算ができないこと' do visit('/try/input') fill_in('simulation_postcode_1', with: '100') fill_in('simulation_postcode_2

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

はじめに 開発の現場では、テストの実行時間がプロジェクトの生産性に直接影響を与えます。特に大規模なプロジェクトでは、テストが肥大化し、時間がかかりがちです。ここ最近は私が普段使っているRSpecというRuby on Railsでよく使われるテストの実行時間を削減するためにも、パラレル実行(並列で実行するテストの方法)の導入の必要性を感じ始めました。 この記事は「テストをパラレル化してみたいよ」という計画についてまとめたものになります。 パラレル実行の必要性 テストの実行時間を短縮することは、開発サイクルを加速し、より迅速なフィードバックを可能にします。これは、バグの早期発見や機能改善の迅速な実装につながり、結果として生産性が向上します。 実現方法の具体化（Myappの例） 例えばMyappアプリというでRSpecのパラレル実行を設定するには、以下の手順に従います： Gemの導入 Gemfi

はじめに 先日、LTイベント「Qiita Night～Rails～」にて登壇させていただきました。 そこで、Railsで大規模Webアプリケーションを 開発するときに知っておきたいテクニックを Qiita の Rails を例にいくつか紹介しました。発表資料はこちらです。 アーカイブ動画もあります。 これまで大規模 Rails で役立つテクニックをそれぞれ記事として紹介しました。 この記事は、LT で話した残りの部分、「Qiita が Rails のコード品質を担保するためにやっていること」を紹介します。 Qiita が Rails のコード品質を担保するためにやっていること それぞれ簡単に紹介していきます！ RuboCop Qiita の Rails では RuboCop を導入しています。RuboCop は Ruby のコードを静的解析し、よくない書き方があると指摘してくれます。 実行

はじめに rspecのletとlet!の違いを忘れてしまうことが多いのでここにメモする 問題 letとlet!はRSpecのヘルパーメソッドで、テスト内で使用するデータを定義するために使われます。しかし、それらはいつデータが生成されるかという点で違いがあります。 このような場合はcourseが複数保存されている必要があるのでlet!で定義しないとなにも保存されていない状態になります。 get "/api/v1/courses" expect(JSON.parse(response.body)[0]["authority"]).to eq(course.authority) expect(JSON.parse(response.body)[0]["travel_mode"]).to eq(course.travel_mode) expect(JSON.parse(response.body)

RSpec を並列に実行してくれるツールとして parallel_tests があります。このツールは CPU 数などの情報から、自動で最適な並列数で RSpec などを複数同時に実行してくれるツールです。これにより通常よりも早くテストを完了することが出来ます。 Qiita でも parallel_tests を使いつつ、複数のマシンを利用して CI での自動テストを回しています。(テストが大量にあるのと、テストを動かすマシンスペックの都合などで、こういう構成になっています。) こういう感じで並列にテストを回す場合は、実行時間ベースでテストを分割して割り振ることで、テスト完了までの時間が早くなります。parallel_tests かつ複数マシンの場合、そうするのがやや面倒なのですが、うまく設定できたので、今回はそのやり方一例として紹介します。 (前提知識): parallel_tests

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

課題 わたしは、Ruby on Rails を使ってアプリケーション開発を本業としているエンジニアです。 Railsで機能を開発すれば、当然Specも書く必要がありますよね。Specを書かないと動作確認ができていない状態でリリースしてしまう危険性があります。 しかし、開発中に多くのクラスやメソッドを書いていると、どのクラスに対して/どのメソッドに対してSpecを書いたのか忘れてしまいます。そうすると、十分に動作を検証していない状態で、PRがマージされてしまうことがあります。 Railsのアプリケーションにおいて、どのメソッドにSpecが書かれていて、どのメソッドには書かれていないのかをSpecファイルを見なくても明らかにしたい!そんなふうに考えたことはないでしょうか。 わたしは、実装を見た瞬間に対応するSpecが存在することが保証されている（または、実装側にSpecが不要であることが明示さ