「The Twelve-Factor App」を15項目に見直した「Beyond the Twelve-Factor App」を読んだ - kakakakakku blog
2012年に Heroku のエンジニアによって提唱された「The Twelve-Factor App」は素晴らしく，アプリケーションをうまく開発し，うまく運用するための「ベストプラクティス」として知られている．2020年になった現在でもよく引用されていると思う．日本語訳もある． 12factor.net Beyond the Twelve-Factor App とは？ クラウド化が進むなど，提唱された2012年と比較すると技術的な変化もあり，今までの「The Twelve-Factor App」で宣言されていた観点以外にも必要な観点やベストプラクティスがあるのでは？という意見もある．そこで，2016年に Pivotal のエンジニアが「Beyond the Twelve-Factor App」を提唱した．The Twelve-Factor App にあった「12項目をアップデート」し，新
OpenAPI Generator で API Client と型を自動生成した話 - BASEプロダクトチームブログ
フロントエンドエンジニアの @rry です。 自分は BASE の Sales Promotion というチームで主に新規機能開発を行っています。このチームでは主にオーナーさんの使う管理画面に新しく機能追加をしています。 そこで、管理画面で使っている API Client と型を、OpenAPI Generator を使って自動生成するようにしてみたのでそのお話を書きたいと思います。 そもそも OpenAPI とは？ https://www.openapis.org/ OpenAPI とは、RESTful Web サービスを記述、生成、使用、および視覚化するための仕様です。 ※ 以前は OpenAPI ではなく仕様自体も Swagger と呼ばれていましたが、現在は仕様自体については OpneAPI と呼ばれており、Swagger というのは OpenAPI を使ったツール群のことをさすよ
OpenAPI Specification ドリブンな開発事例とそれを支えるツール - NTT Communications Engineers' Blog
これは NTT Communications Advent Calendar 2021 3日目の記事です。 こんにちは、イノベーションセンターの松田 (@take4mats) です。 当社の Smart Data Platform (SDPF) のサービスラインナップの多くは、お客さまがサービスご利用に必要な操作を統一的に行うための Web UI に加え、同等の Web API を提供しています。 API 仕様は Knowledge Center にてサービスごとに一般公開されているのをご存知でしょうか？ (Knowledge Center で各サービス内の APIリファレンス のページをご覧ください。例えば こちらのリンク) この一般公開されている API 仕様はサービス開発初期に作成され、開発期間にも重要な役割を果たしています。 本記事では、その中で私が携わったサービスから、 API
Cloud Functions をローカル環境で統合テスト可能にした話 | BLOG - DeNA Engineering
はじめまして。AIシステム部MLエンジニアリンググループ で学生インターンをしている 早坂( @takemioIO ) です。 普段はパケット処理などをやっているのですが、縁あってここでは MLOps の通常業務に携わっております。 私は二ヶ月間インターンとして開発に取り組んでいました。ここではその実装物の一つを紹介します。 この AI システム部 のとあるプロジェクトでは、 Cloud Functions と Cloud Pub/Sub を利用したデータパイプライン を構築しております。 そのプロジェクトは毎日のように変更が取り込まれ、非常に開発が盛んですが一方それゆえに破壊的な変更で足を撃ち抜いてしまいそれによって悩まされることがありました。 さらにはクラウドサービスを利用してるという部分からローカルでの検証環境がありませんでしたので、毎回 GCP に デプロイするしかなく、トライアン
こんにちは Mirrativ CTOの夏です。 現在、ミラティブでは事業部単位でチームや目標を管理しており、エンジニアが所属するチームとして以下の6つがあります。今回はこのうち、エンジニアチームについて、2019年度に行ってきた取り組みの振り返りをしたいと思います。 ライブプラットフォームチーム ユーザの定着を追う マーケ連携チーム ユーザの新規獲得を追う エモモチーム 3Dアバターであるエモモを使った新体験の創出・基礎体験の向上を追う ストリーミング改善チーム モバイル端末でのライブストリーミングの配信・視聴の品質改善を追う インフラチーム クラウド上での安定したインフラ基盤の設計・構築を追う エンジニアチーム お問い合わせ調査、不具合・障害の再発防止、開発体験の向上を追う AI技術部 コミュニティやストリーミングとAI活用の可能性を追う 毎週定例で振り返りを行っており、Confluen
TypeScriptの型定義からJSON Schemaを生成するオンラインツールを作ってみた - Qiita
先日、TypeScript + Tynderから始める宣言的検証生活の記事にて スキーマ検証ライブラリTynderを紹介いたしました。 Tynderとは Tynderは、TypeScriptのサブセット＋独自の拡張文法から成るDSLによって 型の検査 単独の項目の必須・値の長さ・範囲や文字列パターンの検証 複数項目の相関や整合性検証の一部 (Union typeによる) を宣言的に行うことができます。 今回はTynderのスキーマ変換機能を使用して JSON Schema、GraphQL、Protobuf3 のスキーマを生成するオンラインツールを公開しました。 (GraphQL、Protobuf3については実験的機能です) TypeScript (Tynder DSL) → JSON Schema | GraphQL | Protobuf Converter Convert schema
チームのWeb API開発を最適化するSchema Driven Developmentの解説＆実装例 - Qiita
チームでのWeb API開発において、進行を妨げる要因は様々な形で噴出します。 「フロントはバックエンドのAPI実装待ちなので動けません...」「ドキュメンテーションのコストが重い...」「ドキュメントと実装が全然違うので参考にならない...」 また、APIスキーマ設定が不十分だと、ビジネスドメインの最低原則やクライアント側のニーズを理解せずに、バックエンド都合のAPIがそのまま実装される危険性もあります。 そうした問題を解決すべくSchema Driven Developmentと呼ばれる開発手法が生まれました。 Schema Driven Developmentとは？ Schema Driven Development(以下SDD)とはチームにおけるWeb API開発フローを改善する開発手法の一つです。スキーマ駆動開発やSchema First Developmentとも呼ばれています
こんにちは。バックエンドエンジニアの岡本です。 ネットショップ作成サービス「BASE」の新規機能開発や既存機能の改修・運用を担当するShop Groupに所属しています。 今回は私が入社後初めてアサインされたプロジェクトであるメールマガジンApp（※）のアップデートを通して経験したこと・考えたことをバックエンドエンジニアの視点から振り返っていこうと思います。 ※ネットショップ作成サービス「BASE」の拡張機能であるBASE Appsの機能の一つ プロジェクトメンバー構成 ・プロジェクトマネージャー ・デザイナー ・フロントエンドエンジニア ・バックエンドエンジニア(私) メールマガジンAppアップデートの場合、上記4つの役割に対して1人ずつメンバーがアサインされました。1人ずつと言ってもそれぞれの担当を全て1人でやるということではなく、入社間もないメンバーにはメンターがアサインされるなどフ
背景 転職してサーバサイドエンジニアとして、RESTfulなWebAPIドキュメント書く機会が増えた。 RESTの歴史はそれなりに長いため、仕様書の書き方にもベストプラクティスが確立されている。 なので、今更感もあるが、せっかくなのでまとめてみようと思う。 心構え 出来の良いAPI仕様書をマネすること ユーザの対象を意識すること（社内利用か社外利用など。仕様書で意識するポイントが変わるため） トリッキーな使い方をするエンドポイントは疑う 最低限記載すること 共通項目 ドキュメントのメタ情報（バージョン、更新日付など） 常に必要なパラメータ（認証系） 流入制限 エンドポイント（URI） HTTPメソッド（GET、POST、PUT、DELETE、HEAD、OPTIONS、TRACE、CONNECT） Description（概要） Notes（備考） リクエストについて パラメータ（クエリパラ
OpenAPI関連のサイト・ツールまとめ2020.10.29 OpenAPI関連のサイトやツールなどの情報が種々雑多にあるので、自分の中での整理と忘備録として残すためにまとめました。（2020年10月時点） 概要OpenAPIとはOpenAPIという表現が使われた場合、恐らくそれらの多くはOpenAPI Specification（以下OAS）に基づいてJSONやYAMLで記述されたREST APIの仕様書（スキーマ）を指しているように思います。 OASはREST APIの仕様を記述するための規格であり、それ自体がなにかのツールやサービスを提供するものではありません。 とはいえ関連するツールやサービスも普及してきているので、あまり言葉の意味を気にしすぎる必要もないかもしれませんが。 OpenAPI Specification (v3.0.3)Implementer’s Draft (OAS
Python+Flask+Blueprintを使ったAPIサーバ構築 ① 〜構成とサンプルプログラム編〜｜【MENTA】No1.メンターサービスでプロに直接相談しよう！
はじめに バックエンドのAPIサーバとして、Python + Flask + Blueprintの構成のサンプルプログラムを共有します。 Flaskというのは、Pythonで提供されるWebフレームワークです。 Blueprintは、Flaskの中で使われる部品で、アプリを分割することができ、プログラムの保守性を向上させることができるライブラリです。 本記事では、Python + Flask + Blueprintという構成で、テスト環境と本番環境の切り替えがしやすく、モジュールの分割もされ運用しやすい構成をするにはどうすれば良いか、サンプロプログラムを提供することで共有します。 環境 本記事では、以下の環境で動作確認を行いました。 Mac OSX Mojave（10.14.3） Python 3.7.2 Flask==1.0.2 Flask-API==1.1 Flask-Cors==3.
REST API 自動テストツールまとめ - Qiita
REST API のテストを自動化するためのツールを調査した結果のまとめです。 前提として、無料で使用可能なツールのみを対象としています。 分類 一口に REST API のテスト自動化といっても、様々な種類のツールがあります。 今回は独自に分類した以下の 4 種類を順に紹介していきます。 OpenAPI (Swagger) 連携系 GUI 系 CLI 系 CDC testing 系 OpenAPI (Swagger) 連携系 REST API の管理として OpenAPI (Swagger) で仕様を記述することは少なくないでしょう。 OpenAPI 連携系の API 自動テストツールでは、OpenAPI の仕様書をもとに自動テストが実施可能です。 Dredd GitHub - Dredd Star 3.2K もともと API Blueprint のテストツールだったようですが、Open
GitHub Trending RSS
GitHub Trending RSS Star The latest build: 7 October, 2023 All Languages Unknown Languages Unknown languages 1C Enterprise 2-Dimensional Array 4D ABAP ABAP CDS ABNF ActionScript Ada Adblock Filter List Adobe Font Metrics Agda AGS Script AIDL AL Alloy Alpine Abuild Altium Designer AMPL AngelScript Ant Build System Antlers ANTLR ApacheConf Apex API Blueprint APL Apollo Guidance Computer AppleScript
Webでも組み込みでも、何かのシステムを構築したことがある方ならご存知でしょう。 開発というものは、「プログラムを書く作業」よりも、その前の「仕様を決めて文書化する作業」の方がずっとカロリーが高いものです。 最近ちょっとしたAPIを作る機会があり、やはりAPI仕様設計のしんどさと闘いました。 が、API Blueprintという規格とそれに対応するツールを使うことで、そのしんどさが相当な具合で和らぐことがわかりました。 今回はこのAPI Blueprintを全力で推していく記事です。 API Blueprintとは？ https://apiblueprint.org/ API Blueprintは、APIの仕様設計や連携開発を効率的に進めるためのドキュメント仕様です。 Markdownに従った仕様になっているので、そのまま眺めてもある程度理解できるのですが、Blueprintの強みはなんと
背景 今やWebだけでなく、iOS、Android、TV、カーナビといった多数のクライアントでAPIを利用する時代です。 各クライアントでBFFを置く設計もありますが、開発コストや運用コストを考えて同一のAPIサーバを用意し利用することも多いと思われます。 加えてサービスが大きくなってくると外部企業との連携や有志の開発者のためにAPIを公開するケースもあります。 そういった状況下では単にドキュメントベースでやり取りするのは難しく、しばしばAPIとドキュメントの乖離が生まれ負債となっていきます。 そのためこれらの問題を解決できる JSON Schema Protocol Buffers OpenAPI Specification といったスキーマ言語の活用がとても重要になってきます。 今回はOpenAPIについて話します。 他のスキーマ言語の問題点は？ まずOpenAPI以外のスキーマ言語で
しばらく書いてなかったけどメモ程度に dreddとは dreddはopenapi(swagger)やAPI Blueprintの定義を読み込んでテストを実行してくれる便利なツールです。 例えば localhost:8080 でAPIサーバを動かして のようにすればschema.yamlに定義されたAPIの定義に従ってリクエストを送り、レスポンスが仕様に従っているかテストしてくれます。 が、ログインしてtokenを貰ってそのtokenでアクセスするというようなAPIはそのままではテストできません。 hooksという仕組みを使うと、レスポンスからtokenを取得して以後はそれを使う、といった動作が可能になります。 dredd hooks ドキュメントにある通り、hooksは様々な言語で書くことができますが、とりあえずdreddと同じnode.jsでやってみます。 （なぜかと言うと、docker
はじめに フロントサイドとサーバーサイドのエンジニアが、分業する際に大事なものはなんでしょうか。 コンポーネントの切り方の認識合わせ？？そうかもしれません。 それと同様に大切なのが、API仕様の共有の仕方だと思います。 今回、私たちのチームではサーバサイドのAPIの開発に先立ち、フロントサイドの開発をする箇所が出てきたため、 Open API仕様記述ツールを投入して仕様共有してみることとしました。 そもそもOpen API仕様って Open API仕様（OpenAPI-Specification）とは、一言で言ってしまえばREST APIを記述する為の仕様。yamlやjsonに近い形式で記述することができます。 GitHub - OAI/OpenAPI-Specification: The OpenAPI Specification Repository もともとSwaggerっていうフレ
ドキュメントちゃんと保守できてますか？ API開発とドキュメントの保守は切っても切れない問題です。 仕様の記述はもちろんのこと、サンプルを試せるAPIクライアントや、仕様に則った実装になっているかテストも自動化したいですよね。 本記事では、現在開発中のAPIアプリケーションで、実際に僕が試行錯誤していく中でたどり着いたベストプラクティスを紹介しようと思います。 アーキテクチャ iOSアプリのバックエンドとしてJSONを返すAPIサーバー Rails6 × MySQL5.7 on Docker いつもの というお買い物アプリです。 ドキュメント何で書いてますか？ Excel => つらい Markdown => つらい 何らかのDSLを用いて生成するツール => 素でマークダウンを書くのはつらみが深いので何かしらツールを使いましょう。 apiary, api blueprint, APIDO
こんにちは。CTOの河内です。 多くのプロジェクトがスタート時はそうである通り、我々のプロジェクトもAPI仕様がありませんでした。 最初は規模が小さく問題として認識されていなかったのですが、規模が大きくなり、また開発者の入れ替わりを経験するごとに、「この API って何返してくるの？」という問いに答えられる人が段々といなくなってきました。 「ソースが仕様だ」とサーバの実装を読めばもちろん答えられるのですが、ソースコードを読み解く時間がかかるため効率的ではありません。 また、サーバ実装が唯一の情報源となるため、ロジックが何かおかしいと感じても、それが仕様なのかバグなのか判断できない状態でした。 API仕様を先に定義し、通信上の疑問にはAPI仕様で答えられるようにしたかったのです。 これは一般的な課題で、日本CTO協会が2019年12月に公開した DX Criteria DX Criteria
こんにちは、データAI部でPythonエンジニアをしている平田(@JesseTetsuya)です。普段は、PoCとデータをもってくる、というところ以外全部やる、というスタンスで開発業務を行っています。 日頃は、Flask1.1.4を利用していましたが、2021年5月11日にFlask2.0へのメジャーバージョンアップがありました。 メジャーバージョンアップということもあり、多くのアップデート項目がありました。そこで、特に日頃の業務に関わりそうなアップデートについて当記事にまとめていこうと思います。 Flaskとは？ Flaskは、PythonistaのArmin Ronachertによって2010年に初回リリースされました。いまでは、 Armin Ronacherを筆頭にPalletプロジェクトと言う名前でFlaskを含む、Flaskに関連する各ライブラリのメンテナンスがPalletプロジ
[GitHub] Markdownの「シンタックスハイライト」に対応している言語一覧 - ねこの足跡R
Markdownでプログラムのソースコードを記述する場合に使うバッククォート3つで囲う「コードブロック」ですが、気の利いた環境だと自動的にシンタックスハイライトによって予約語やコメント分などを色分けして見やすく表示してくれます。 GitHubも例外ではなく、各リポジトリに常設されているWikiやREADMEなどをMarkdownで記述した場合は自動的にシンタックスハイライトされます。 メジャーな言語であればそのまま記述すればよいのですが、例えばYAMLやJSONなどのデータ形式や、Apacheの設定ファイルなどそもそもカラーシンタックスに対応しているのか、対応している場合キーワードはなんだろうと迷いますよね。 今回はGitHubが対応しているカラーシンタックスの設定一覧をまとめておきます。 ハイライトのやり方 GitHubで利用できる言語一覧 定義 一覧 おまけ 抽出方法 参考ページ ハイ
![[GitHub] Markdownの「シンタックスハイライト」に対応している言語一覧 - ねこの足跡R](https://cdn-ak-scissors.b.st-hatena.com/image/square/e5bf125aecc59cdb944df8797e85524099779984/height=288;version=1;width=512/https%3A%2F%2Fogimage.blog.st-hatena.com%2F820878482973262145%2F6801883189061409297%2F1701758116)
はじめに こんにちは！株式会社80&Companyの技術広報です。 弊社の開発部署では毎週火曜日の朝9:30から社内勉強会を行なっています。 今回の記事は社内のエンジニアがフロントエンド業務を担当していた際に、API周りの作業改善のため、スキーマ駆動開発の導入提案を社内勉強会で発表したものを紹介します。 スキーマ駆動開発を検討中の方は参考にしてみて下さい♪ 読者の対象 スキーマ駆動開発に興味がある方 スキーマ駆動開発の導入を検討している方 スキーマ駆動開発とは スキーマ駆動開発とはAPIのスキーマを最初に定義して、定義をもとにバックエンドやフロントエンドの開発を進める開発手法です。はじめにAPIのスキーマ定義をするため、フロント <-> バックエンド間におけるAPI仕様のずれを防ぐことができます。API仕様に変更を行う時も、API仕様書を変更してフロントエンド、バックエンドそれぞれの開発を
はじめに 最近WebAPIを触る機会があって懐かしくなったので、以前とある案件でかじったAPI Blueprintでも布教してみます。 APIの仕様をMarkdown拡張記法で記述できる言語です。 慣れるまでは正直書きづらいですが、元がMarkdownなのでSwaggerに比べるとまだ書きやすい方だと思います。 今度記事にしますが、先日Frisby.jsというWebAPIのテスティングフレームワークを触るためにJWT認証を使った簡単なWebAPIを作ったので、サンプルとしてAPI Blueprintで仕様書を書いてみました。 FORMAT: 1A HOST: http://localhost/api # Sample API Frisbyを触ってみるために最低限の機能だけで作ったWebAPI ## ユーザ登録 [POST /users] 新規ユーザを登録する + Request (appl
最近は API Blueprint で仕様書を書くことが多かったのですが、Swagger が世界標準になるかもしれない、ということもあり、開発の効率化を進めるためにも概要をまとめてみようと思った次第です。 Swaggerとは Swagger は RESTful APIを構築するためのオープンソースのフレームワークのことです。「Open API Initiative」という団体がRESTful APIのインターフェイスの記述をするための標準フォーマットを推進していて、その標準フォーマットがSwaggerです。Swaggerには多くの便利なツールが提供されていることもあり、多くのメリットを享受できそうです。 Swagger Spec を書いておけば自動的にドキュメント生成までしてくれ、それだけではなく、ドキュメントから実際のリクエストを投げられる優れものです。 Swaggerのツール群 ツール
週刊Railsウォッチ（20200210前編）Railsのベンチマークジェネレータ、長いバックグラウンドジョブと戦う、Timestamp切り詰めの謎、Open APIツールほか｜TechRacho by BPS株式会社
2020.02.10 週刊Railsウォッチ（20200210前編）Railsのベンチマークジェネレータ、長いバックグラウンドジョブと戦う、Timestamp切り詰めの謎、Open APIツールほか こんにちは、hachi8833です。そういえば明日は祝日ですね。コロナウイルス流行の様子が早速ビジュアライズされたようです。 元記事: コロナウイルスの黙示録的な広がりをリアルタイムで追跡するサイトが公開 | ナゾロジー 「まあこれで何かわかったとしても自分らに打てる手は限られてますし😷」「情報の動き激しくて...😅」（以下延々） 参考: CNN.co.jp : 新型ウイルス、潜伏期間中の感染例は「誤り」 独当局 各記事冒頭には⚓でパーマリンクを置いてあります: 社内やTwitterでの議論などにどうぞ 「つっつきボイス」はRailsウォッチ公開前ドラフトを（鍋のように）社内有志でつっつい
from flask import Blueprint, request, abort, jsonify from models import db, User # api Blueprint作成 http://host/api 以下のものはここのルールで処理される api = Blueprint('api', __name__, url_prefix='/api') # エンドポイント http:/host/api/users, GETメソッドのみ受け付ける # routeは複数指定も可能、methodsはリストなので複数指定可能 @api.route('/users', methods=['GET']) def list_user(): # クエリーパラメータ取得 request.args.get # 第一引数:パラメータ名、default=で初期値、type=で変換する型を指定できる
以前API BlueprintでAPI仕様書を書くという記事を書いた。 あれからまぁまぁ経ったがAPI Blueprintの先行きは暗い。 仕様もツールも進化せず最新のnodeでは動かないものまででている。 さすがに困ったので、 swaggerを使うことにしたのだが、 こちらも何か良くなったのかと言えば、 現状も変わってないようだ。 (-_-;) めんどい YAML直接編集で仕様書書くとかやってられないし、 swagger editorも使い勝手が最悪だし。 何か良い方法はないかと探したら良いものがあった。 Stoplight Studio APIテストのGUIで仕様書を出力するツール。 これならまだ使えそうか。 ソースはGithubで管理しているので、 ドキュメントはmarkdownにしたい。 あと、見やすさを重視してHTML表示もしたい。 そのあたりもカバーしよう。 ヾ(・ω<)ﾉ"
はじめに 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
前職で使っていたツールの dredd について書いてみたいと思います。 dredd 公式サイト: Dredd — HTTP API Testing Framework — Dredd latest documentation 公式サイトより、issue のほうがいろいろ情報あるかも: Issues · apiaryio/dredd dredd は openapi の仕様書をもとに、テストを自動で行ってるツールです。 (※api blueprint で書かれた仕様書でもOK) すでに、openapi の仕様書を管理しているプロジェクトであれば、すぐに導入してテスト自動化ができます。 ※openapi は v2 も v3 も対応していますが、v3 はまだ試験的な導入らしいので、場合によっては正しく動作しない可能性あり。詳しくは公式のドキュメント参照。 Dredd — HTTP API Test
sample.apib �c� �U pfU �U FORMAT: 1A # Sample API ## Sample API について Sample API は、与えられた URL にアクセスしたオーディエンスに対するレコメンド記事を返す、架空の API である。 ## API 共通のエラー形式 ### クライアント側が原因の場合 400 Bad Request を返す。ボディ部は以下の形式とする。 ``` {"message":"エラーメッセージ"} ``` 全APIに共通のエラーメッセージとして、以下を定義する。 | エラーメッセージ | 意味 | |:----------------|:-----| | Missing parameters | 必須(required)のパラメータが1個以上指定されていない | | Invalid parameters | 必須のパラメータが指定さ
Say you have developed a web API and now want to show it to the world. Next comes documentation, and guess what — there’s a tool for that. But, in a sea of API documentation generation tools, which one is suitable to your specific environment? This comprehensive list of API documentation solutions has been curated specifically for web API providers. They take an API source, ideally in the form of
「API仕様書を書くことになったけど、どうやって書けばいいかな？」 「API仕様書からそのまま記述したAPIのお試しみたいなこと出来ないかな？」 こんにちは、タカフです。 とある案件でAPI仕様書を書くことになりました。API仕様書って書くのが地味に面倒ですよね。 API仕様書は大抵誰かに見せる為に作るから体裁を整えないといけない。 体裁を整えないといけない＝Excel又はWord又はGoogleDocumentで書く。 でも頻繁にAPI仕様書を書いてるわけではない場合テンプレートなんて無いから、体裁含め書いていかなければいけない。 これがツラい。 なので僕は、API仕様書を書くとしたらMarkdown形式で書いてhtml変換を圧倒的にオススメ致します。 その理由と使い方を下記に述べていきます。 API仕様書をMarkdownで書くメリット API仕様書をMarkdownで書くと以下のよう
Beyond the Twelve-Factor App を元にした アプリケーション開発のプラクティス考察 - FLINTERS Engineer's Blog
こんにちは、エンジニアマネージャーの堀越です。 ちょっと前、TLで割と盛り上がっていたこちらの書籍をポチり読んでみました。いいですよこの本！！ gihyo.jp こちらの書籍の第3章に Beyond the Twelve-Factor App なるものの紹介があり、色々調べて考察した結果を社内勉強会で発表したのでブログにも書き起こしておきます。 Beyond the Twelve-Factor App とは？ Pivotalという会社が提唱したアプリケーション開発のためのベストプラクティス集です。 実は元ネタに Heroku が考案したThe Twelve-Factor App があるのですがこちらは内容も考え方も古く、Beyond の方はクラウドを使う点での考慮点が含まれているのがポイントです。 以下のリンクからE-Mailを登録するとPDFがダウンロードできます。 tanzu.vmwa
TL;DR 8年近く稼働していたPHPのシステムをGoでリプレースしようと試みた経緯と経過報告。 Goを書きたいエンジニアは絶賛募集中だよ 自己紹介 twitter: Go里🚴♂️ 2015/10からHowtelevisionにジョイン Go/PHP/JS/EngineeringManager 開発合宿に自転車で行く図 副業 2018/11からhey社でも副業を始めGoでのWebアプリケーション開発を手伝い始めた [FYI]ハウテレビジョン開発者ブログ ハウテレビジョン 2010年創業 2019年、マザーズ上場 新卒向けの「外資就活ドットコム」と、中途向けの「Liiga」というキャリア支援サービスをやってる会社 社員40名、総従業員数は100名超 インターン生がめちゃくちゃ働いてる変な会社 技術顧問: Naoya (2015年〜) 外資就活ドットコム 2010年にローンチされた就活サー
開発部の三浦です。 今回はDREDDを使用してAPIをテストする方法を書いていこうと思います。 Dreddとは https://dredd.org/en/latest/ openapi(swagger)やAPI Blueprintの定義を読み込んでテストを実行できる便利なツールです。 hooksという仕組みを使うと、リクエストに動的に値を組み込んだり、レスポンスで返ってきたtokenをセットし認証な必要なテストを実行したりということが可能になります。 dredd hooks hooksは様々な言語で書くことができます。 GoNode.js (JavaScript) Perl PHP Python Ruby Rust といった言語に対応しています。自分の得意な言語を選択して記述することができます。 私はJavaScriptをよく触っていたので、今回はJavaScriptで記述していこうと思い
「The Twelve-Factor App」を15項目に見直した「Beyond the Twelve-Factor App」を読んだ - kakakakakku blog
2012年に Heroku のエンジニアによって提唱された「The Twelve-Factor App」は素晴らしく，アプリケーションをうまく開発し，うまく運用するための「ベストプラクティス」として知られている．2020年になった現在でもよく引用されていると思う．日本語訳もある． 12factor.net Beyond the Twelve-Factor App とは？ クラウド化が進むなど，提唱された2012年と比較すると技術的な変化もあり，今までの「The Twelve-Factor App」で宣言されていた観点以外にも必要な観点やベストプラクティスがあるのでは？という意見もある．そこで，2016年に Pivotal のエンジニアが「Beyond the Twelve-Factor App」を提唱した．The Twelve-Factor App にあった「12項目をアップデート」し，新
Swagger備忘録 - Qiita
開発手法 主要な開発手順としては、以下二つのものがあるようです。 トップダウン形式： SwaggerEditorでSwagger Specificationを編集、定義 SwaggerCodegenでSwagger Specificationからソースコードを生成 ボトムアップ形式 既に存在するREST APIのソースコードからSwagger Coreのアノテーションなどを使用しSwagger Specification定義 生成されたSwagger SpecificationをもとにSwagger UIによって、RESTAPIをドキュメント化 競合ツール OpenAPIの仕様に基づくツールとしては、他はRamlとAPI BluePrintが有名どころである。 Raml RESTful API Modeling Languageの略でその名の通りREST APIを設計するための言語。 その
- + books: (array[Book]) + + books: (array[Book], fixed-type) 公式にしっかり書いてありますね。無駄にGithubとか調べてしまった。。 何が起きたの？ API BlueprintでAPIドキュメントを作成していたときに、どうにもarrayの中身がドキュメント化されない事が気持ち悪くなったので調べてみた。 例えば。次のドキュメントだとこのように変換される。
“Beyond the Twelve-Factor App” & “The Twelve-Factor App”から学びAWSで実践する (2)APIファースト - Qiita
解説 本ファクターはオリジナルにはなく、Beyondで追加されたものです。最近のアプリケーション開発においてAPIは重要性を増しており、非常に重要なファクターになります。APIファーストの良い点を以下のようにまとめています。 アプリケーションの機能要件はAPIの利用を通じてすべて満たされる。UI部分はWebやモバイルアプリといった様々な形式で自由に提供できる あらゆる機能をAPIで実装し、UIはそのAPIを利用して構築するというのはすでに当然の構成です。AndroidやiOSといったモバイル端末、Webブラウザ、PC用のデスクトップアプリケーションと同じアプリケーションを提供するとしても、対象端末ごとに最適なユーザーエクスペリエンスを提供するためには、それぞれに適したUI実装が必要となります。その中で、機能要件は共通なロジックとしてAPIで提供されるのはしかるべき構成になります。 ステーク
はじめに 業務でAPI Blueprint と aglio を使ってAPI仕様書を作成したので、 API Blueprint で仕様書を記述 aglio を使うための Docker 環境の構築 aglio を使って、 API Blueprint で記述したファイルを読みやすいドキュメントに変換 という一連の手順を備忘録として残しておく。 今回作成した、API Blueprint で記述したファイルと、 aglio を使うDocker 環境のリポジトリは以下。 API Blueprintとaglioとは API Blueprint Web APIの仕様を表現するための様々な文法を持つ言語のこと。 記述形式はMarkdown。 ただのテキストファイルなので、Gitなどのバージョン管理ツールとも相性が良い。 公式サイト API Blueprint | API Blueprint aglio ap
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
ミラティブ エンジニアチーム四季報（創刊号） - Mirrativ Tech Blog
バックエンドエンジニアから見たプロジェクトの軌跡 - BASEプロダクトチームブログ
APIドキュメントの書き方をまとめてみる - あらにわ
OpenAPI関連のサイト・ツールまとめ | GiFT（ギフト）株式会社
API Blueprintで仕様書を作成しつつモックサーバも起動する手順 | MONSTER DIVE
OpenAPI で REST API のスキーマ作成 - Carpe Diem
dreddで認証付きのAPIをテストする - Qiita
Open API仕様記述ツールを比較してみた - Qiita
ぼくのかんがえたさいきょうのAPIドキュメント運用🤹♀️ - Qiita
独自の外部 DSL 編集をエディタでサポートする - FLINTERS Engineer's Blog
Flask 2.0.xのアップデート項目紹介 - Classi開発者ブログ
スキーマ駆動開発 with Open API - Qiita
API Blueprintのススメ - Qiita
Swaggerの概要をまとめてみた。 - Qiita
Flask REST API サンプル - Qiita
SwaggerでOpenAPI仕様書を作成、HTMLやMarkdownに変換する
redoclyで作成したAPI仕様書からモックを作る - Qiita
👷テストツール dredd👷 openapi の内容でテストを実行する - Qiita
Sample of API Blueprint document
Ultimate Guide to 30+ API Documentation Solutions
API仕様書はMarkdownで書いてhtml出力がベスト（API Blueprint）
CakePHPからGoに移行してクリーンアーキテクチャ目指し2年経った話 - Qiita
Dreddを使用してAPIをテストする - 株式会社CoLabMix
API Blueprint(aglio)で、生成されたSchemaのarrayにitemsがない
Docker環境でAPI Blueprint+aglioを使ってAPI仕様書を作成する - Qiita