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

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

タグ:editor

IBM Cloud から提供されている 30 日間無料 Kubernetes サービスIBM Kubernetes Service 、以下 "IKS")環境を使って利用することのできるコンテナイメージを1日に1個ずつ 30 日間連続で紹介していきます。

環境のセットアップや制約事項については Day0 のこちらの記事を参照してください。

Day 19 からはプログラミング・開発系コンテナとその GUI ツールを中心に紹介してます。Day 22 は実行可能な API ドキュメントを記述するエディタである Swagger Editor イメージをデプロイする例を紹介します。
swagger



【イメージの概要】
アプリケーション開発において、ドキュメント準備は(直接、プログラミングと関わる点が少ないという意味においても)比較的面倒な作業です。が、最近は Swagger  API ドキュメントとか Open API ドキュメントと呼ばれる、画面上で直接実行可能なドキュメンテーション技術が生まれたことで、プログラマーにとっても大事かつ役立つ作業となりました。

この Swagger API ドキュメントは特殊な JSON や YAML フォーマットで記述することで実現できるのですが、この特殊なフォーマットを知らなくても作れるようになるのが Swagger Editor です。今回紹介するのは、この Swagger Editor が使えるようになるコンテナイメージです。


【イメージのデプロイ】
まずはこちらのファイルを自分の PC にダウンロードしてください:
https://raw.githubusercontent.com/dotnsf/yamls_for_iks/main/swaggereditor.yaml

今回の Swagger Editor も特にパラメータ指定不要で、そのままデプロイすることができます。以下のコマンドを実行する前に Day 0 の内容を参照して ibmcloud CLI ツールで IBM Cloud にログインし、クラスタに接続するまでを済ませておいてください。

そして以下のコマンドを実行します:
$ kubectl apply -f swaggereditor.yaml

以下のコマンドで Swagger Editor 関連の Deployment, Service, Pod, Replicaset が1つずつ生成されたことと、サービスが 30080 番ポートで公開されていることを確認します:
$ kubectl get all

NAME                                  READY   STATUS    RESTARTS   AGE
pod/swagger-editor-6f94c7c8d6-6rc58   1/1     Running   0          6s

NAME                     TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE
service/kubernetes       ClusterIP   172.21.0.1       <none>        443/TCP          27d
service/swagger-editor   NodePort    172.21.237.213   <none>        8080:30080/TCP   8s

NAME                             READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/swagger-editor   1/1     1            1           7s

NAME                                        DESIRED   CURRENT   READY   AGE
replicaset.apps/swagger-editor-6f94c7c8d6   1         1         1       8s

この後に実際にサービスを利用するため、以下のコマンドでワーカーノードのパブリック IP アドレスを確認します(以下の例であれば 161.51.204.190):
$ ibmcloud ks worker ls --cluster=mycluster-free
OK
ID                                                       パブリック IP    プライベート IP   フレーバー   状態     状況    ゾーン   バージョン
kube-c3biujbf074rs3rl76t0-myclusterfr-default-000000df   169.51.204.190   10.144.185.144    free         normal   Ready   mil01    1.20.7_1543*

つまりこの時点で(上述の結果であれば)アプリケーションは http://169.51.204.190:30080/ で稼働している、ということになります。HATOYA はこの URL が管理ダッシュボードの URL になっているので早速実行してみます。ウェブブラウザを使って、アプリケーションの URL(上述の方法で確認した URL)にアクセスしてみます:
swagger1


この GUI 画面(プレビュー画面)を使いながら Swagger API を作り、必要であればローカルファイルにエクスポートすることも可能です:
swagger2


【YAML ファイルの解説】
YAML ファイルはこちらを使っています:
apiVersion: v1
kind: Service
metadata:
  name: swagger-editor
spec:
  selector:
    app: swagger-editor
  ports:
  - port: 8080
    protocol: TCP
    targetPort: 8080
    nodePort: 30080
  type: NodePort
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: swagger-editor
spec:
  replicas: 1
  selector:
    matchLabels:
      app: swagger-editor
  template:
    metadata:
      labels:
        app: swagger-editor
    spec:
      containers:
      - name: swagger-editor
        image: swaggerapi/swagger-editor
        ports:
        - containerPort: 8080

Deployment 1つと、Service 1つのシンプルな YAML ファイルです。一応解説を加えておきます。アプリケーションそのものは 8080 番ポートで動作するように作られているため、NodePort 30080 番を指定して、外部からは 30080 番ポートでアクセスできるようにしています(NodePort として指定可能な番号の範囲は 30000 ~ 32767 です、指定しない場合は空いている番号がランダムに割り振られます)。また ReplicaSet は1つだけで作りました。


デプロイしたコンテナイメージを削除する場合はデプロイ時に使った YAML ファイルを再度使って、以下のコマンドを実行します。不要であれば削除しておきましょう:
$ kubectl delete -f swaggereditor.yaml


【紹介したイメージ】
https://hub.docker.com/r/swaggerapi/swagger-editor


【紹介記録】
Dayカテゴリーデプロイ内容
0準備準備作業
1ウェブサーバーhostname
2Apache HTTP
3Nginx
4Tomcat
5Websphere Liberty
6データベースMySQL
7phpMyAdmin
8PostgreSQL
9pgAdmin4
10MongoDB
11Mongo-Express
12Redis
13RedisCommander
14ElasticSearch
15Kibana
16CouchDB
17CouchBase
18HATOYA
19プログラミングNode-RED
20Scratch
21Eclipse Orion
22Swagger Editor
23R Studio
24Jenkins
25アプリケーションFX
262048
27DOS Box
28VNC Server(Lubuntu)
29Drupal
30WordPress

「複数人でプログラミングを体験する」ための環境を作ることになった場合、その環境をどう実現すればいいかを考えました。
computer_mob_programming


より具体的にはこんな状況・前提だと思ってください(余談ですが DX の影響なのか、業務でこういう需要を耳にする機会が増えているように感じてます):
- 複数人でアプリ開発(プログラミング)体験を行いたい
  - 参加者は1チーム5~6人程度
  - 参加者は普段 Windows を使っている。Mac, Linux の経験はほぼゼロ
  - 参加者はコマンドプロンプトなどの CLI は普段使っていない
  - 参加者はプログラミングに関してはほぼ初心者
- チームで1つのアプリを作って動かす、という体験をしたい
- 体験期間は半日、長くて1日
- 参加者の PC に何かをインストールしたり、アカウントを作ったり、設定したりする場合、作業できるのは当日
  - 参加者 PC 以外の Linux サーバーなどに主催者が事前準備するのは自由
- 全員オンライン参加、zoom などのオンラインツールの利用に問題はない


最後の前提は必須ではないですが、昨今だとどうしてもこの条件になるかなあ、ということで加えています。


この状況下でどういう仕組を用意すれば、目的に会ったプログラミング体験ができるかを考えます。


候補案1
「とりあえず正攻法でやってもらう」方法です。ソースコードは git などでリポジトリ管理して(必要であれば事前にサンプルを用意して)、各自はリポジトリから clone したソースコードを画面共有を併用しながら手元で編集して動かしてもらう。環境が許せば Visual Studio Code の LiveShare なども使って共同編集する。。

・・・これが本来のスジであることは重々承知しているし、将来的に役立てることを意識するならこの形を学ぶべきだとは思っています。ただプログラミング初心者相手に半日~1日でここまでやるには少しハードルが高すぎる気がしています。環境準備段階でのハードルの高さもありますし、git も教えないといけないし、LiveShare 使うならアカウントから準備しないといけないし、その上でほぼ未経験のプログラミングをオンラインで・・・ 何を作るかにもよりますが、Hello World 程度すら厳しいかも。。

#おまけとして、業務においてはこの手の「管理者権限が必要な作業」自体が実施上のリスクとなる可能性があることを経験談として触れておきます。


候補案2
参加者がそこそこ Linux に詳しい人だったら、Linux サーバーにサンプルを含むソースコードを集める形にして、全員が個別に SSH や VNC でログインして vi でプログラミングすればよい、です(同時編集によるコンフリクトはいったん目をつぶりますw)。同じサーバーでアプリを動かせば、それぞれがウェブブラウザで動作確認もできます。

でも今回、この形で行うにはハードルが高すぎます。普段から SSH やコマンドプロンプトを使うような人ではなく、ましてやキーバインドにクセのある vi を使わせるのは厳しそうです。

手段の1つとして「SSH でログインして nano エディタを使う」ことや「Linux に X Window まで導入した上で、VNC でログインして簡易テキストエディタを使う」も考えられます。これらはありっちゃあり、懸念があるとすれば慣れない CLI や Linux での操作でしょうか。nano エディタも vi や Emacs ほどクセはありませんが、Linux コマンドを無視することもできませんし、CTRL キーや ALT キーと組み合わせてのメニュー操作は慣れるまでは苦労するかも、という印象です。

その辺りの苦労も体験の一部とみなしてやってもらう、という案は相手次第ではあり、かな。。


ここまで書いておいてアレですが、個人的にはここまでの案1&2は現実的ではないかな、と考えています。オンラインでなければまだしも、オンラインでこの慣れてないはずの作業のサポートをするのはかなり難しそうという印象を持っています。理想どおりに実施するのことがかなり厳しそう・・・


候補案3
いわゆるローコード・ノーコード環境を事前に Linux サーバーに用意して、この環境を使う方法です。

これは目的に対する解答になっていると思います。Linux に例えば Node-REDScratch などをインストール&起動しておいて、参加者は画面共有しながらウェブブラウザで(CLI ではない、ここがでかい!)アクセスしてコーディング作業を行う、というものです。なんといっても参加者の PC に何かを事前にインストールする必要がない(=準備段階のリスクが低い)点がポイントです。ローコードなのでプログラミング開始時の敷居が低く、1日でもそこそこ学べるものだと思っています。

懸念が2つあるとすれば、この環境が1つは共同作業に適したツールかどうかの判断や対応が必要になる点と、もう1つはやはりどうしてもできることの制限があることです。ローコードであるが故に「ループ」や「条件分岐」といったコーディングの基礎のようなことを行う選択肢が少なかったりするわけです(ループができないとは言わないけど「整数配列をその数だけループさせながら加算する」とかは Node-RED では難しい)。動くものは作れるかもしれないけど、プログラミング体験という当初の目的を達成できるものになるかどうか、が鍵だと感じました。


候補案4
実はいま個人的にはこれが一番いいかも、と考えているのが、この候補案4です。概要はこんな感じ:
(1) サンプルを含むソースコードを事前に Linux サーバーに用意する
(2) 同サーバーに Eclipse Orion をインストールする
(3) 参加者はウェブブラウザで Eclipse Orion にアクセスして、サーバーのソースコードを直接編集
(4) 誰か一人(主催者でもよい)がサーバーでアプリを起動して動作確認

(1) のサンプルはあらかじめ最低限動くものを用意しておきます。目的にもよりますが、Hello World 表示だけのウェブアプリでもかまわないと思ってます。

(2), (3) の Eclipse Orion は「オンラインテキストエディタ」です。サーバー上で起動し、サーバー内の特定フォルダ以下のテキストファイル(ソースコード)をオンラインで編集できるようになります。テキストエディタとしての基本機能があるので、便利にコーディング作業をすすめることができます。オンラインエディタは必ずしも Orion エディタでなくてもいいと思ってますが、オープンソースであることや docker 環境下で使える便利さもあっておすすめです。

(4) そして編集したソースコードを使って実際に動かし、可能であれば全員がウェブブラウザで動作も確認する、というものです。

この方法も候補案3同様に、参加者 PC 側での事前準備が不要です。CLI 操作もなく、全て GUI 作業です。Java なり JavaScript なりの実行環境もサーバーだけに事前に用意しておけばいいので参加の負担はありません。実際にコーディングも行うので、内容も(分岐やループから、外部API へアクセスしての AI 体験みたいなことまで)自由度高く設計可能です。

プログラミング環境も、Eclipse Orion インスタンスを1つだけ起動して、全員で同じインスタンスに接続して共同プログラミングしてもいいし、Eclipse Orion インスタンスを複数起動して別々に接続させることで同じテーマで個別にプログラミングすることもできます。純粋なプログラミング環境を比較的容易に準備する方法と考えます。


こちらの懸念はあらかじめ用意しておくサンプルをどうするかと、候補案3と異なり「実際にプログラミングを行う(しかも半日~1日で)」ことになる点です。データベースを使うかどうかなど、サンプルに合わせたカリキュラムの検討が必要だと思っています。その代わり「プログラミング体験」という目的に合っていて、「まず一度体験してもらう」ための案としては自由度も高くて悪くない、と思っています。

 

実を言うと前回このブログエントリを書いたのは、今日のエントリへの前フリでした:もともと以下で紹介する 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








 

このページのトップヘ