まだプログラマーですが何か?

プログラマーネタとアスリートネタ中心。たまに作成したウェブサービス関連の話も http://twitter.com/dotnsf

タグ:editor

実を言うと前回このブログエントリを書いたのは、今日のエントリへの前フリでした:もともと以下で紹介する Swagger Editor を使う様子を紹介したかったのですが、そのためには扱う題材となる API が必要でした。というわけで簡単な仕様で、かつ試験的にクロスオリジン問題を解決することのできる(←ここ大事!)REST API を Node-RED で作ってみる、というのが上記の内容でした。同様に自分で管理可能な API があればそれを使って読み替えていただいてもいいのですが、そうでない場合まずは上記エントリを参照して、この後の紹介で管理する REST API を作っておいてください。


さて本題は「REST API のドキュメントをどのように用意するか」です。REST API の仕様書として最低限必要な情報は HTTP メソッドと URL のパス、実行時に与えるパラメータ、結果、そしてその API が何をするものかをざっと紹介したものでしょうか?気が利いているものだと各パラメータ毎の必須/オプションの情報、エラー時の情報などがあったりしてより便利になります。上記の Node-RED で作った API の場合だと対象の API は1つでこんな感じでしょうか:
メソッドパスパラメータの指定方法パラメータとその意味実行例結果の Content-Type結果
GET/getDateURLパラメータtimestamp : タイムスタンプ値(オプション、未指定時は現在時刻)curl -XGET 'http://xxx.com/getDate?timestamp=1000'text/plain指定した日付時刻の文字列


このドキュメントでもある程度は理解できると思いますが、もう少し便利に、というか、Swagger という標準フォーマットを使ってドキュメントを作ってみます。その際に便利なのが Swagger Editor です。Swagger Editor はここにアクセスしてオンライン版をそのまま使うこともできますし、Docker イメージやソフトウェアをダウンロードして専用環境下で利用することもできます。今回はオンライン版を使って紹介します。

Swagger Editor を開いて、API ドキュメントを yaml と呼ばれるテキストフォーマットで書いていきます。今回の例だとこんな感じでしょうか:
swagger: "2.0"
info:
  description: "俺の API"
  version: "0.0.1"
  title: "俺の API"
host: "**********.mybluemix.net"
basePath: "/"
tags:
- name: "myapi"
  description: "俺のAPI"
schemes:
- "http"
- "https"
paths:
  /getDate:
    get:
      tags:
      - "myapi"
      summary: "時刻を文字列で取得する"
      description: "現在時刻または指定したタイムスタンプ値の日付文字列を返す"
      produces:
      - "text/plain"
      parameters:
      - in: "query"
        name: "timestamp"
type: "number"
format: "integer" description: "タイムスタンプ値" responses: 200: description: "成功"

この内容を Swagger Editor の画面左に入力します。するとこの Swagger で定義した Open API ドキュメントが画面右に表示されます:
2017091001


今回定義したのは GET /getDate という1つの API です。ここをクリックすると展開され、パラメータなどより詳しい情報が表示されます。API ドキュメントとしても便利ですが、この Swagger によるドキュメント最大の特徴は「実行できる」ことです。このページから AJAX によるリクエストを発行して API を実行します。一般的には AJAX でリモートサイトにアクセスするにはクロスドメイン問題を考慮する必要がありますが、今回用意した API は(そのための目的もあって)クロスドメインからも実行できるような HTTP レスポンスヘッダを設定しています。というわけで実行してみましょう。"Try it out" と書かれたボタンをクリックします:
2017090902


するとパラメータ部分が入力可能な状態になります。今回は timestamp という必須ではないパラメータを指定できるようにしていることがわかります。とりあえずはここには何も設定せずにそのまま実行してみます:
2017090903


実行するには "Execute" と書かれたボタンをクリックします。すると実行した時の curl コマンドなどと一緒に実行結果も表示されます。この API はパラメータなしで実行すると現在時刻のテキストを返すようになっており、実際に実行したタイミングの日付時刻が表示されます:
2017090904


次にパラメータを指定した上で実行してみます。timestamp に 1000 と入力してみました。これはタイムスタンプの値が 1000 になる日時(1970年1月1日午前零時から1000ミリ秒後)を指定したことになります:
2017090905


この状態で "Execute" ボタンをクリックすると、実行結果は 1970/01/01 00:00:01 になるはずです。API が正しく動いていることがドキュメントの中から実行して確認することができました(クロスドメイン問題を抱えたままだとここでの実行は失敗します):
2017090906


と、これが Swagger で作った API ドキュメントの魅力です。 最後にここで定義した Swagger ドキュメントをエクスポートして(Swagger Editor 上ではない)別のサーバー上でも動くようにしてみます。今回は Node.js 上で実行できるような形式でエクスポートしてみましょう(サーバーサイド JavaScript である Node.js 上で実行する場合はクロスドメインは意識する必要がありません)。画面メニューの "Generate Server" から "nodejs-server" を選択します。すると自動的にダウンロードが始まり、nodejs-server-server-generate.zip というファイルがダウンロードされます:
2017090907


この zip ファイルを Node.js がインストールされたシステム上に展開し、"npm install" 後に "npm run start" すると起動します:
$ cd nodejs-server-server
$ npm install
$ npm run start

> api@0.0.1 prestart /home/pi/src/nodejs-server-server
> npm install

up to date in 5.819s

> api@0.0.1 start /home/pi/src/nodejs-server-server
> node index.js

Your server is listening on port 8080 (http://localhost:8080)
Swagger-ui is available on http://localhost:8080/docs

起動したドキュメントページ(上記例だと http://localhost:8080/docs)にアクセスすると Swagger Editor の右ペインでプレビューとして見ていた部分が表示されます:
2017091002


実際にパラメータを指定するなどして実行することも可能です:
2017091003


以上、自分で作った API に対する実際に動かせる Swagger ドキュメントを作り、そのドキュメントを自分のサーバー上で動かす、という一連の手順を紹介しました。開発者としては API の仕様書を読み解くだけでなく、実際に動かして返ってくる値やそのフォーマットを確認しながら利用できるので、自分が API を使って作ったアプリがうまく動かなかった時の問題切り分けにも使えるツールになるので非常に便利です。

自分はテキストエディタにはこだわりがあります。

Vz エディタから始まり、vi(vim)、Emacs、・・と使ってきました。現在はこんな感じで使い分けています:
  • Java コードの記述には Eclipse
  • JavaScript の記述には ATOM
  • サーバーにターミナルログインして使う場合は vi(vim)
  • PC でマークダウンを記述する場合は Boostnote
  • それ以外はメモ帳かサクラエディタ

大きくは PC 環境なのか、サーバー環境なのかの違いです。基本的にサーバーにログインして使う場合は vi(vim) ばかり使ってます。一方 PC 環境の場合、Java だけは例外的に Eclipse でないと使いづらいのですが、それ以外はあまりこだわりはありません(最近、周囲の影響で ATOM を使い始めました)。実はメモ帳を使うことも結構多いのですが、議事録などはマークダウンで書くことが多く、その時は Boostnote を使ってます。


さて、クライアント環境では「好きなエディタをインストールして使う」ことも可能ですが、サーバー環境ではそうもいかないケースがあります。特に X Window システムが導入されていない CUI 環境の場合、そもそもテキストエディタの選択肢がほとんどなく、標準搭載されている vi を使うか、環境によってはたまに使うことの出来る Emacs を使うか、という形になることが多いと思ってます。ただいずれもキーバインドにクセがあり、サーバー環境初心者がメモ帳感覚でサーバー上のエディタを使うのが難しいという一面もあります。

そんな中、比較的普通(?)のキーバインド感覚で使えるのが "nano" エディタです。GNU プロジェクトの1つであり、GUI なしのターミナル環境で使える軽量エディタです。vi や Emacs だと「ファイルを保存」したり「エディタを終了」したりするにも専用のキーバインドを覚える必要があるので、初心者のとっかかりにはかなり高いハードルになってしまいますが、nano エディタは「常時表示されているメニューから選ぶだけ」なので、そのあたりのハードルは低めに設定されているといえます。 個人的にはあまり利用する機会のなかった nano エディタを調べてみました。


【インストール】
nano エディタは多くの環境で標準コマンドとして導入済みのことが多いと思いますが、導入されていない場合はインストールする必要があります。環境に合わせて、以下のいずれかのコマンドで導入してください:
(CentOS/RedHat 系の場合)
$ sudo yum install nano

(Ubuntu/Debian/Raspbian 系の場合)
$ sudo apt-get install nano


【起動】
コマンドラインからそのまま
$ nano

と入力することで nano エディタが新規ファイル作成モードで起動します。またはファイルの名前と一緒に
$ nano test01.txt

と入力すると、指定したファイルを編集するモードで起動します。


【画面】
実行中のターミナル内でフルスクリーンエディタとして起動します。画面下部にはメニューが常時表示されます。普通にカーソルキーで上下左右にカーソルを移動させることができ、キーを入力するとそのまま画面に表れます:
20170711


【メニュー】
以下、各メニューの項目を紹介します。メニュー項目を利用する場合はファンクションキーか Ctrl キーと表示されている文字を同時に押します( "^G" と表示されている場合は Ctrl + G です)。また以下で "M-*" という表記になっている場合は 「ESC キーを押してから * キー」という意味です:


^G (F1) : ヘルプ

以下のようなオンラインヘルプ画面を表示します。^Y / ^V で次/前ページへ移動、^P / ^N で次/前行で移動します( ^Y / ^V は編集画面でも同様に動きます)。^X でこのメニュー画面を終了します:
2017071102


^X (F2) : 終了

nano エディタを終了します。未保存の編集中のファイルがある場合は保存するかどうか確認した上で終了します(Y で保存、N で変更破棄、^C でキャンセル)。
2017071101


^O (F3) : ファイル書き出し

編集した内容をファイルに書き出します。ファイル名が指定されている場合はそのファイルに、ファイル名が指定されておらず、新規作成モードの場合はファイル名を指定して保存します:

2017071104

ESC キーとの併用でファイルフォーマットを指定したり、別のファイルの最後尾に追加する、という指定も可能です。


^J (F4) : テキスト整列

現在のコンソールサイズに合わせてテキストを整列し直します。



^R (F5) : ファイル読み込み

カーソル位置に別のファイルの内容を挿入します:

2017071103

^X で「コマンドの実行結果を挿入する」という指定もできるようです。


^W (F6) : 検索

指定したテキストを、現在のカーソル位置から後方に向かって検索し、最初に見つかった所へカーソルを移動します:

2017071105

ESC キーを組み合わせることで検索方向を前方に変更したり、正規表現指定が可能になったりします。


^Y (F7) : 前ページへ移動


^V (F8) : 次のページへ移動


^K (F9) : 1行カット

カーソルのある行をカットします。カーソル行は削除されますが、後述のペーストで元に戻せます。


^U (F10) : 1行ペースト

「カットのアンドゥ」で、^K でカットした行をペーストします。


^C (F11) : カーソル位置の確認


テキストが長くなって一画面で全てが表示しきれないような場合に、現在のカーソル位置が全体の何行目の、何文字目にあるのか、という情報を出力してくれます:

2017071106



^T (F12) : スペルチェック

内蔵されている spell を使ったスペルチェック機能らしいのですが、自分の環境ではうまく動きませんでした。。



以上、nano エディタの基本的な使い方について紹介しました。本格的なソースコード編集は手元の専用エディタを使うとして、サーバーにログインして作業が必要になった場合に vi や emacs が分からなくても、この nano エディタを使うことができれば、最小限の設定ファイル書き換えなどはできそうなので、これら2つのエディタに不慣れな人は重宝するかもしれません。



なお、nano エディタの解説はこちらの wiki にも詳しく紹介されていました。設定ファイルによってシンタックスハイライトなどもできそうです。こちらも参考にどうぞ:
https://wiki.archlinuxjp.org/index.php/Nano








 

このページのトップヘ