25000行超えのAPIドキュメントを分割した話

2024/03/22 54 users APIドキュメント 知見 スキーマ駆動開発 伊藤 弊社

はじめに COUNTERWORKSバックエンドエンジニアの伊藤です。 この記事ではAPIドキュメント分割の知見を紹介します。 弊社では OpenAPI を使用したスキーマ駆動開発を採用しています。 1ファイルで管理していたところ、25000行を超える行数となり管理コストが高くなっていました。 そこで分割作業を実施したのですが、どの... 続きを読む

TypeScript のような構文で OpenAPI のスキーマを定義する TypeSpec

2024/01/27 76 users TypeScript スキーマ 構文

import "@typespec/http"; using TypeSpec.Http; model User { id: string; name: string; birthday?: utcDateTime; address: Address; } model Address { street: string; city: string; state: string; zip: string; } @route("/users") interface Users { list(@query limit: int32, @query skip: int32): User[]; cr... 続きを読む

GitHub、SDKを刷新。今後はOpenAPI仕様の生成ツールで生成したSDKを提供へ

2024/01/14 58 users GitHub Octokit SDK 刷新 APIクライアント

GithHubは、今後はAPI仕様を記述する業界標準であるOpenAPIに対応した生成ツールで生成したAPIクライアントをSDKとして提供することを明らかにしました。 現在まで同社は「Octokit」と呼ばれるSDKを提供しています。これはGitHubの開発者が、外部のアプリケーション開発者のために、さまざまな言語でGitHub APIを呼び出... 続きを読む

zod-to-openapiで、既存のAPI実装にOpenAPIドキュメントを後付けする | Memory ice cubes

2023/11/01 13 users API実装 Cloudflare Workers API

昔々あるところに、既存のWeb APIの実装がありました。 それなりに実装を進めた後に、天の声が言いました。「OpenAPIのドキュメントを公開したい」と。 さて、あなたならどうする？っていうニッチな問いに対する一つの答えとして。 ルーターごと乗り換える？ たとえば今回でいうと、元のAPIはCloudflare Workersにデプロ... 続きを読む

あらゆるアプリやウェブサイトのOpenAPI仕様を自動生成してくれるChrome向け拡張機能「OpenAPI DevTools」を使ってみた

2023/10/27 11 users ウェブサイト 自動生成 Chrome向け拡張機能 アプリ 仕様

ウェブ上の通信で利用されるAPIのうち、OpenAPIを使用して記述されているAPIを検知して自動でOpenAPI形式の仕様を作成してくれるツールが「OpenAPI DevTools」です。Chrome向けの拡張機能としてリリースされており、簡単に使えるとのことなので実際に使って試してみました。 AndrewWalsh/openapi-devtools: Effortlessly... 続きを読む

最近のGoのOpenAPI Generatorの推しはogen - ぷらすのブログ

2023/09/12 8 users optional YAML プラス コード ブログ

はじめにogen の良いところgRPC ライクな interfacenull や optional に対してちゃんと型を付けようと努力しているOpenTelemetry の標準サポートおわりにはじめにOpenAPI の yaml ファイルから Go のコードを生成する OSS ツールは何種類か存在します。 よく使われるのはOpenAPITools/openapi-generatorやdeepmap/oapi-c... 続きを読む

OpenAPI Generatorに適したOpenAPIの書き方 - ZOZO TECH BLOG

2023/03/15 23 users Swagger WEAR API クライアント 自動生成

はじめに こんにちは！　WEARバックエンドブロックの高久です。 WEARではOpenAPI（Swagger）を使って、アプリやWebのクライアントが利用するAPIを定義しています。そして先日、開発効率化のためにOpenAPI GeneratorでOpenAPIからAPIクライアントコードを自動生成、活用できるように整備をしました。その中でOpenAPI Gene... 続きを読む

OpenAPI (Swagger) まとめ - Qiita

2022/11/09 71 users Swagger NEST Rails API node.js

はじめに 自分は実務でReact×TypeScriptを利用したフロント周りとNode.js(Nest)やRailsを用いたバックエンド(API)の開発をしています。 本記事では、OpenAPIを用いたAPI設計の書き方及び、Swaggerの説明と使い方についてまとめていきます。 この記事の対象者 プログラミング初心者から中級者 APIの基礎を理解している人 ... 続きを読む

OpenAPI + Zod で型安全な API クライアント出力

2022/09/28 50 users Zod openapi-generator REST API

バックエンドが OpenAPI（REST） で API 仕様を公開している場合、 フロントエンド側で OpenAPI の仕様から、 型安全、かつ API 仕様通りに型定義と API クライアントを生成したい場合があり、 現状　API クライアント生成系ライブラリとして、以下のいずれかが候補に上がるかと思います。 openapi-generator 様々な言語... 続きを読む

OpenAPI からなるべく生成するフロントエンド開発

2022/10/10 59 users seya スキーマ スクリプト REST API 一挙大

こんにちは。 スキーマから何かを生成するのが大好きな seya と申します。 今の会社では REST API のスキーマを OpenAPI で記述しているのですが、それを活用して何かしらを生成するスクリプトをよく書いています。 そんなネタがそれなりに溜まってきたので一挙大放出しようというのがこの記事です。 具体的には次のよう... 続きを読む

GitHub Actionsで「OpenAPI の自動バージョニング」から「API Clientのnpmパッケージ生成」までを完全自動化 〜bypass機能を利用してみました〜 - BASEプロダクトチームブログ

2022/09/12 10 users GitHub Actions 松田 マネージャー 完全自動化

Platformグループでマネージャーをしている松田（ @tadamatu ） です。 この記事に書いてあること GitHub Actions を利用し 「OpenAPI の自動バージョニング」から「API Clientのnpmパッケージ生成」までを完全自動化 したのですが、その際に ハマったこと、工夫したこと が結構あったので、シェアしておきたいと思い書... 続きを読む

OpenAPIを使ったRailsスキーマ駆動開発 - ドワンゴ教育サービス開発者ブログ

2022/07/07 15 users ドワンゴ教育サービス開発者ブログ

はじめに サービス構成 レポジトリ一覧 サーバー側Railsアプリ クライアント側Railsアプリ 開発の流れ 利用ツール swagger-cli committee-rails 不具合1: ファイルの分割 不具合2: $refとnullableの同時使用 json-schema openapiの記法に合わせた機能拡張 openapi-generator-cli (Ruby client) 不具合1: 中途半端な型チ... 続きを読む

企業ページリプレイス ~OpenAPIの活用~ - PR TIMES 開発者ブログ

2021/11/01 5 users テンプレートエンジン Smarty React リプレイス

こんにちは、21新卒エンジニアの柳です。 先日、PR TIMESの企業ページをSmartyというテンプレートエンジンからReactへリプレイスを行いました。その際にOpenAPIを社内のプロジェクトで初めて導入したので、OpenAPIのメリットや活用方法について書きたいと思います。 プロジェクトの背景 OpenAPIの説明に行く前に、企業ペ... 続きを読む

OpenAPI? What Is That? Is That Tasty?

2021/10/29 13 users

Transcript OpenAPI？ なにそれ？ おいしいの？ 2021/10/29 えにしテック永和技術交流会 @cafedomancer Shohei Umemoto @cafedomancer えにしテックでプログラマをや っています。2015年10月に新 卒入社したのでちょうど7年目 になります。さいきんの趣味は ヤマノススメの影響ではじめた 登山です。もうすぐ30歳になる ... 続きを読む

openapi-generator-cli による TypeScript 型定義

2021/03/23 14 users TypeScript github.com 一筋縄 アセット

openapi-generator-cli を利用すると、OpenAPI 定義から TypeScript で利用可能なアセットを生成することができます。しかし生成結果を最適なものとするためには、OpenAPI 定義自体に少しコツが必要で、一筋縄にはいかないことがあります。 【本稿サンプルリポジトリ】https://github.com/takefumi-yoshii/openapi-egner... 続きを読む

OpenAPI generator と TypeScript で型安全にフロントエンド開発をしている話 - SmartHR Tech Blog

2020/08/25 87 users TypeScript GENERATOR Generate

こんにちは、SmartHR でフロントエンド開発を担当している @Tokky0425 です。 この記事では、私のプロダクトでの OpenAPI generator を使ったフロントエンド開発の取り組みを紹介していきます。 目次 OpenAPI とは 「ラクラク分析レポート」の DX 上の課題 OpenAPI generator とは 実際に generate してみる 生成ファイ... 続きを読む

OpenAPI や Protocol Buffers のおかげで開発がかなり捗っている話 - Medley Developer Blog

2020/08/21 193 users grpc CLINICS Protocol Buffers

こんにちは、インキュベーション本部エンジニアの加藤です。 主に CLINICS アプリの開発を担当しています。 はじめに CLINICS アプリの開発では OpenAPI や gRPC を利用しています。 OpenAPI と gRPC の間には何の関係もないのですが、どちらも API の仕様をスキーマ言語で記述するという点では共通しています。 今回は... 続きを読む

Go言語におけるOpenAPIを使ったレスポンス検証 - ZOZO Technologies TECH BLOG

2020/06/15 13 users ZOZOTOWN Opena リプレイス Go言語 API開発

こんにちは、ECプラットフォーム部の権守です。普段はZOZOTOWNのリプレイスに関わるID基盤とAPI Gatewayの開発を行っています。 ID基盤やAPI Gatewayの中身についてもいずれ紹介したいと思いますが、本記事では、ID基盤のAPI開発で取り入れているGo言語におけるOpenAPIを使ったレスポンス検証について紹介します。 OpenA... 続きを読む

API 設計: gRPC、OpenAPI、REST の概要と、それらを使用するタイミングを理解する | Google Cloud Blog

2020/04/16 712 users grpc REST API タイミング 設計

※この投稿は米国時間 2020 年 4 月 11 日に、Google Cloud blog に投稿されたものの抄訳です。 ほとんど&#... 続きを読む

本当に使ってよかったOpenAPI (Swagger) ツール | Future Tech Blog - フューチャーアーキテクト

2019/10/08 483 users Swagger フューチャーアーキテクト 冒頭 https

サードパーティ製のツール本家からは上述のツールが提供されていますが、サードバーティ製の様々なツールが世の中には存在します。 エコシステムが成熟しているのもSwaggerを利用するメリットの一つですね。 https://openapi.tools/ 冒頭のとおり、このサードパーティ製のツールの中で実際に利用して良かったツールを3つ... 続きを読む

マイクロサービスにおけるWeb APIスキーマの管理 ─ GraphQL、gRPC、OpenAPIの特徴と使いどころ - エンジニアHub｜若手Webエンジニアのキャリアを考える！

2019/08/22 405 users 近年 利点 パフォーマンス マイクロサービスアーキテクチャ

近年流行しているマイクロサービスアーキテクチャにおいては、「どういった通信方式を選ぶか」が開発の効率やサービスの信頼性、パフォーマンスを大きく左右します。この記事では、GraphQL・gRPC・OpenAPIそれぞれの利点と適切な使い分けについて解説します。 マイクロサービスにおけるWeb API管理の重要性 Schema Fast ... 続きを読む

OpenAPI/Swagger 2.0 APIドキュメント生成用CFnテンプレート ｜ DevelopersIO

2019/05/17 8 users DevelopersIO CodePipeline API

渡辺です。 APIを開発するとき、 OpenAPI/Swagger 2.0 API で定義をゴリゴリ書いていけば、API Gatewayへのデプロイも簡単ですし、ドキュメントも生成できて超便利です。 ドキュメントの生成ツールは色々あるようですが、やっぱり自動的に生成したいですよねぇ。 毎回、コマンド打つのも面倒です。 CodePipelineでHTML吐... 続きを読む

RubyKaigi 2019で登壇した時のCFPや準備の話

2019/04/24 21 users CFP 未来 RubyKaigi 2019 うち 準備

今回は未来の発表者のために発表までの準備や流れについて覚えているうちに書いていこうと思います。 発表内容はこちらを参考にしてください。 RubyKaigi 2019でOpenAPI 3について登壇しました 採択されたCFP 採択されたCFPを公開している例はある123ので、こちらでも公開していこうと思います。 ## Title How to use Op... 続きを読む

OpenAPIによるスキーマファースト開発の実施サンプルとCloud Runについて - OPTiM TECH BLOG

2019/04/17 58 users スキーマファースト開発 Cloud Run 高橋 去年 普段

こんにちは、インダストリー事業本部 医療チームの高橋（@yukey1031）です。 去年のクリスマス以来の投稿です。AMIAS（アミアス）をお願いします。 さて、今回は自身の周辺業務で普段行っているOpenAPIによるスキーマファースト開発の実施サンプルと先日Google Cloudより発表された「Cloud Run」について少し触れてみた... 続きを読む

OpenAPI GeneratorでRESTful APIの定義書から色々自動生成する #OpenAPI - こまどブログ

2019/01/13 292 users xlsx SPA OpenAPI Generator API

APIの定義を書く：Excel仕様書はもういやだ RESTful APIを提供するサーバと、そのAPIを利用するクライアント（たとえばSPA）とを並行で開発しようとするとき、まずAPIを定義して、それに基づいてサーバ／クライアント双方の実装を進めようと考えるのは自然だと思う。 そうと決まれば、「API仕様書_20190110.xlsx」と題す... 続きを読む