最近、Golang (+echo) で REST API サーバを開発する機会があったのですが、テストを書いたら API ドキュメントを自動生成するような仕組みを作るために試行錯誤したのでメモです。 方針 API ドキュメントの生成にはtest2docを利用 テストを実行すると API Blueprint 形式でファイルを自動生成してくれそう 該当するメソッドの上にコメントを書くことで最低限の説明は記述できそう README には gorilla/muxと julienschmidt/httprouterのサンプルしか載っておらず echoでうまく動くかは試してみるしかなさそう テストから生成された .apibファイルをaglioみたいなツールにかませば HTML ファイルとして API ドキュメントができそう プロジェクト構成 github.com/danimal141/rest-api

frasco.io 2024 著作権. 不許複製 プライバシーポリシー

In this article we cover best practices for writing Node.jsNode.js is an asynchronous event-driven JavaScript runtime and is the most effective when building scalable network applications. Node.js is free of locks, so there's no chance to dead-lock any process. REST APIs, including topics like naming your routes, authentication, black-box testing & using proper cache headers for these resources. O

こんにちは！今年もコナン映画にいってきました、コナンでは服部派のエンジニア結城(@super_manner)です(*´ڡ`●) さて、今回はAPIをチームで開発するうえでつよーい味方になるツールを２つ使い比べた結果をご紹介しようと思います!! そもそもPawとInsomniaとは？ 双方ともREST APIクライアントです。 Paw paw.cloud Insomnia insomnia.rest APIを作成していると、POSTする必要があったり、User-AgentやRequestHeaderによる制約を受けたりで プラグイン追加が加速したりしますよね。 うっかりそのまま他のサイトを閲覧して全部がxmlで表示されたりすることもしばしば。 そんな煩わしさも、これらのクライアントを使うことで開放されるのです!! APIをメインに開発されている方にはもはや必需品になっているかもしれませんね。

こんにちは、バックエンドエンジニアのじょーです。大規模なサービスのAPIを開発する際に、ルールを決めずに開発していると無秩序なコードが散見される運用がしづらいAPIになってしまいます。また、ルールを決めたとしても共有が上手くいかないなどの理由で守られなくなってしまうこともあると思います。 本記事では、APIを運用しやすくするために、ただルールを決定しただけではなく、ルールを守るためにそれぞれ仕組み化をしたことを紹介します。 APIのレスポンスを統一する デコレーターを使ってレスポンスの定義を綺麗に書く パラメーターを統一する Validatorによりパラメーターの明記を強制する コーディング規約を守る LinterとSideCIを導入して修正とレビューの自動化 Linterのルールを適度に調節する 1. APIのレスポンスを統一する ここで言うAPIのレスポンスを統一するというのは、返すA

JavaScriptにおいて、XMLHttpRequest（XHR）に代わるAPIとして、Fetch APIというものが提供されるようになりました。XHRと同等の機能を提供しますが、Fetch APIはよりシンプルで強力です。使い方を学んでみましょう。 基本的な使い方 Fetch APIはPromiseベースの簡単なAPIです。リクエストするにはfetch(url)を呼び出すだけです。 fetch('file.txt') fetch()メソッドはPromiseを返します。PromiseはResponseオブジェクトとして解決されます。返ってきたPromiseを実際に処理してみましょう。 fetch('file.txt') .then((response) => response.text()) .then((text) => console.log(text)) .catch((error

タイトルは釣り、かつ、自分のための備忘録です。 マイクロサービスアーキテクチャでサービスを構築すると、APIサーバをサービスごとに立てるわけですが、 ブラウザ上のJSエンジンからAPIサーバを叩く時に避けて通れないのが、Same-Origin Policy（同一生成元ポリシー）によるCORS (Cross-Origin Resource Sharing)制限です。 これを回避するには、APIサーバ側でAccess-Control-*ヘッダを適切に返す必要がありますが、どう設定するべきかの情報が意外と少ないので（自分的）これが決定版！　という設定を考えてみました。 結論 nginxの場合の設定例です。 server { listen 80; server_name site.localhost; charset utf-8; root /var/www/app/public; locatio

JSON SchemaでAPI開発を自動化する Tweet このエントリは弊社の英語ブログのAutomating your API with JSON Schema — Commerce Hack の翻訳です。 APIのドキュメントとクライアントライブラリの保守には苦労します。時間もかかるし、ドキュメントの更新をついつい忘れてしまうこともよくあります。私たちは、こういう作業をするのにいいツールはないものか、ずっと探していました。 そして見つけたのが JSON Schema です。これは本当にクールな技術で、私たちはこれを、APIのドキュメント生成、クライアントライブラリ内のロジック、そして自動化テストの中で活用しています。ここではその活用法を紹介したいと思います。 JSON Schema とは何か? JSON Schema とは、JSON object の記述と検証のための標準で、概略はこ

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? 初めまして、qsona (tw) と申します。Ruby on Rails Advent Calendar 2016 6日目の記事になります。 Rails歴は10ヶ月で、もちろんAdvent Calendarへの参戦も初です。 全体的に生意気な内容と思いますが、 じゃんじゃんマサカリ投げてください お手柔らかにお願いします。 はじめに 環境 JSONを返すAPIで、データベースはRDBを想定してます。 あんまり関係ないですが一応、Rails5 (api mode) + MySQLを想定しています。 マイクロサービスとしてのバックエンドに使

7. APIドキュメントは書くことが多い ● Host ● Path ● HTTPメソッド(GET, POST, PUT, DELETE, ...) ● Request Header, Body ● Query Parameter ● Response Status Code ● Respose Header, Body ● Authrozation, Authentication ● etc...

jsonapi-resourcesはこちら cerebris/jsonapi-resources: A resource-focused Rails library for developing JSON API compliant servers. 下準備 インストールまで いつものなのでサクサクいきます。 $ bundle init # Gemfile source 'https://rubygems.org' gem 'rails', '5.0.0.rc1' $ bundle install $ bundle exec rails new . --api # 上書きを確認されるので適当にYesしておく # Gemfile # 以下を追記。 # rubygemsにあるのだとRails5に対応していないのでgithubから取得していることに注意。 gem 'jsonapi-resourc

2023 追記 2023 年現在では、以下の文章では採用を見送っている OpenAPI を使えば OK という雰囲気です。 Web APIの設計 作者:Arnaud Lauret翔泳社Amazon TL; DR ドキュメント生成にはkevinrenskers/raml2htmlを使った ドキュメントはRAML - RESTful API modeling languageで書いた RAMLにはJSON SchemaとJSONを記載できる APIで返ってくるJSONはRailsアプリのrequest specでJSON Schemaを使ってテストした JSON Schemaはr7kamura/json_worldで生成した ドキュメントに載せる例示のJSONもJSON Schemaからgin0606/screijiを使って生成した 上記の方法だとリクエストパラメタとドキュメントの整合性を担保

ども、@kimihomです。 API に関する基礎的な話で、なぜ API が重要なのか、APIの実装で注意する点について記述した。 今回はAPI開発において最も頭を悩ます、認証の問題について考えてみたい。 API における認証 よくあるログインが必要なページを考えてみていただきたい。 通常のWebアプリケーションであれば、Cookieという仕組みを使って毎回Webサーバーにアクセスするときにsession idというものを送信し、それとユーザー情報を紐付けたデータを取ってくることで、どんなユーザーからリクエストが来たのかをWebアプリケーション側で判断することができる。これにより、私たちはいつも閲覧しているWebアプリケーションが自分専用の画面として見れるようになっている。 これがAPIになると話は違ってくる。Cookieという仕組みが使えないのである。ということで、なんとかしてAPIにア

$ bin/rails g scaffold user name:string mail:string password:string invoke active_record create db/migrate/20151214145437_create_users.rb create app/models/user.rb invoke test_unit create test/models/user_test.rb create test/fixtures/users.yml invoke api_resource_route route resources :users, except: [:new, :edit] invoke scaffold_controller create app/controllers/users_controller.rb invoke test_un

追記：この記事はバージョンが古いものです。より新しい情報について Swagger 2.0 に対応した ASP.NET Web API のドキュメントを作成する こちらをご覧ください。 ASP.NET Advent Calendar 2014 17 日目 の記事です。前回は iwate さんの ASP.NETプロジェクトからDBコンテキストを切り離してマイグレーションする です。 この記事では、Swagger を使った ASP.NET Web API のドキュメントを生成する方法について書きます。 ASP.NET Web API のドキュメント生成といえば、NuGet Package「Microsoft.AspNet.WebApi.HelpPage」を使う方法 がありますが、やや欠点があります。 その欠点をカバーできる Swagger の概要を確認した後、実際に ASP.NET Web AP