SwaggerでAPIを定義してモックアップを作る

REST APIの仕様定義には色々ありますが、Open API Initiativeでも標準ツールとして採用されている SwaggerをつかってAPI仕様を記載しモックアップを作ってみましょう。
Swaggerはユーザが多いのもあって周辺ツールの充実と多言語対応が良いので今から採用するならオススメです。

Swagger.yamlAPI仕様を記述する。

SwaggerではAPIの仕様をswagger.yamlで記載しますが、
swagger-editorというツールが非常に便利です。
ツールとしてインストールも出来ますし、オンラインでも使えます。
http://editor.swagger.io/#/

まずはこんなyamlを書いてみます。

swagger: '2.0'
info:
  version: "0.0.0"
  title: サンプル api
# Describe your paths here
paths:
  # This is a path endpoint. Change it.
  /users:
    get:
      description: |
        メンバ一覧取得API.
      parameters:
        -
          name: size
          in: query
          description: Size of array
          required: false
          type: number
          format: number
      responses:
        # Response code
        200:
          description: ユーザデータ(List)
          schema:
            title: ArrayOfUsers
            type: array
            items:
              $ref: '#/definitions/User'
  /users/{id}:
    get:
      description: |
        メンバ取得API.
      parameters:
        -
          name: id
          in: path
          description: user id
          required: true
          type: number
          format: number
      responses:
        # Response code
        200:
          description: ユーザデータ
          schema:
            $ref: '#/definitions/User'
definitions:
 User:
  type: object
  properties:
    id:
      type: number
    name:
      type: string
    age:
      type: number

簡単に言うと、
「/users」で一覧が取得できて
「/users/{id}」でUserID指定のデータが取得出来るというものです。
またdefinitionsのところでUserデータ型を指定しています。

ソースの生成

これで、Springのソースを出力してみましょう。
SwaggerからはNode、GoServer、JAX-RSPythonRails等色々な言語の実装を自動生成できますが、SpringBootだと起動が楽なので今回はSpringでいきます。
「Generate Server」から「spring」を選ぶと出来たソースがZipで落ちてくるので解凍するとMavenプロジェクトになっています。
もうこれでサーバの基礎は動きます。
楽勝ですね。

それでは動かしていきます。
まずはPomを開いて42行目あたりの「provided」行を削除しましょう。

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
            <scope>provided</scope>       ←この行削除
        </dependency>

レスポンス内容をそれらしく作る

Swaggerで生成されるモックはレスポンス内容は空っぽで生成されます。
なのでレスポンス内容は自分でモックコードを書く必要があります。

ソースの中のio.swagger.api.UsersApiControllerを開いて「// do some magic!」と書かれているところにモックコードをこんな感じで書きます。

@javax.annotation.Generated(value = "class io.swagger.codegen.languages.SpringCodegen", date = "2016-11-08T06:41:55.099Z")
@Controller
public class UsersApiController implements UsersApi {
    public ResponseEntity<List<User>> usersGet(@ApiParam(value = "Size of array") @RequestParam(value = "size", required = false) BigDecimal size
    ) {
        // do some magic!
        User user1 = new User();
        user1.setId(BigDecimal.ONE);
        user1.setName("aaa");
        User user2 = new User();
        user2.setId(BigDecimal.TEN);
        user2.setName("bbb");
        List<User> list = new ArrayList<>();
        list.add(user1);
        list.add(user2);
        return new ResponseEntity<>(list,HttpStatus.OK);
    }

    public ResponseEntity<User> usersIdGet(@ApiParam(value = "user id", required = true) @PathVariable("id") BigDecimal id ) {
        // do some magic!
        User user1 = new User();
        user1.setId(BigDecimal.ONE);
        user1.setName("aaa");
        return new ResponseEntity<>(user1, HttpStatus.OK);
    }

これでOK。
あとは起動して、「http://localhost:8080/」にアクセスすればSwaggerUIがみれます。
f:id:GARAPON:20161108172530p:plain

TryItOutをおしてみると
f:id:GARAPON:20161108172537p:plain

こんな感じで動いていますね。

ダイバーシティとインクルージョンの関係

女性活躍推進法もありダイバーシティダイバーシティ言われてますよね。
それが単にダイバーシティではなく「ダイバーシティインクルージョン D&I」と呼ばれるようになったのでインクルージョンとは何のことか調べてみた。

ダイバーシティ

まず基礎となるダイバーシティ
「女性活用」と理解すると間違ってないけど正解じゃない。
ダイバーシティの意味は多様性。英語圏だと国籍の多様性の意味が強いそこから宗教や価値観の多様性。
いろんな人がいるよね。いろんな人がいてうまくやっていこうぜっていう意味でダイバーシティというのが
30年ぐらい前にアメリカで叫ばれ始めた。
んでラテン系とか、女性とか、LGBTとかの人たちの多様性を受け入れて、いろんな人が居て違ったものの見方ができる人が集まる組織が健全であり強いのだ
という流れになった。

それが日本に入ってきたときに日本ではまずは女性が注目されて話が始まりいつの間にか「女性活用」として誤用されるようになってしまった。
まあ間違っていないのだけど、本来もっと広い視点の話だと抑えておけばOK。

インクルージョン

英語の意味的には「内包」日本語で適した意味だと「受け入れる」という感じかな。
上記のダイバーシティで多様な人が集まるとどうしても緊張や対立が起こる。これはしょうがない。
ある会社Aが会社Bに吸収されたときに「元A社」と「元B社」で中が悪いとか対立だとかそういうのが起こるのを考えればすぐ分かると思います。

ここからどうやって多様性を活かしながら組織の力を発揮するか。
そこにおいてインクルージョンの考えが出てきたようです。それが2000年頃。
何がインクルージョンの正解かというのは答えがありませんが、「健全な本音議論を通して」多様性をもった力の発揮が行えるというのが主流の考え方のようです。

つまり表面的な数値目標の達成ではなく、ダイバーシティインクルージョンが本当に意味あるもので、そこから価値を得ることが経営戦略上重要であるというような強い確信を持って本気で議論をしていくことが大切のようですね。

オープンAPIとOpen APIととWeb APIとREST APIの違い。

なんか色々バズワード化してますよね。
言葉が色々あって不明瞭なので少し整理してみましょう。

定義の狭さから掲題とは逆順で説明していきます。

REST API

これは文字通り、RESTアーキテクチャに従って作られたAPIのことです。
RESTはアーキテクチャのため、RESTの考え方にしたがって作られているWebAPIを「RESTful API」と呼称します。

RESTが何かという話は
garapon.hatenablog.com

Web API

HTTP通信などのWeb技術を用いて構築されたAPI(サービスインタフェース)が「WebAPI」と呼ばれます。
そのため、「RSETful API」もWebAPIの1つで「SOAP」やgoogle社の「gRPC」、facebook社の「graphAPI」などもWebAPIに含まれます。

オープンAPI

先にカタカタの「オープンAPI」を説明します。
オープンAPIとは「ある企業が提供するAPIのうちサードパーティーがアクセス可能なAPI」の事を指します。
サードパーティの定義はEuro Banking Association*1では以下5段階に分けられており、Private以外を指します。
- Public:誰でもアクセス可能
- Acquaintance:一定契約のもと誰でもアクセス可能
- Member:コミュニティに属するメンバーのみがアクセス可能
- Partner:パートナーとの合意に基づきアクセス可能
- Private:グループ内のみ
一般的に言われる「オープンAPI」はAcquaintanceに含まれますね。GoogleMapsAPIとか。

OpenAPI

さて、わかりにくさの頂点英語で書かれる「OpenAPI」これはなにかというと「Open API Spesification」の略称。
これがなにかというと、RESTful APIインターフェイスを記述するための標準フォーマットを推進する団体「Open API Initiative」が、The Linux Foundationの協力のもとでマイクロソフトGoogleIBMIntuitPayPal、3Scale、Apigee、Capital One、Restlet、SmartBearらによって結成されてました。
んで、Swagger specifications が寄贈されOpen API Spesificationという名称に変更。Swagger specificationsは「Swagger」と呼称されていたのでOpen API Spesificationが「Open API」と呼称されてしまったりしている。
まじめんどい。
正式文書の中ではちゃんと「Open API Spesification」とかいてあるのだけど人によっては「Open API 2.0」とかかいてあるとろがありわかりにくい。
なので日本のドキュメントではカタカナと英字で書き分けられることが多いです。
全銀協の表記も「オープンAPI
「オープンAPIのあり方に関する検討会」の設置について - 全国銀行協会
ちなみに英語では上記の「オープンAPI」を示すときは「Open APIs」と書かれる

無限に繰り返すスライドショーの作り方

勉強会が始まるまでの案内用に無限に続くスライドショーを作ったのでメモ
※PowerPoint2016です。

以下のように設定して後は放置。

1、無限ループするよう設定
「スライドショータブ」
 ⇒「スライドショーの設定」
  ⇒「オプション」
   ⇒「Escキーが押されるまで繰り返す」をチェック
   
2、自動的に切り替わるように設定
全シートを選択してから
「画面切り替えタブ」
 ⇒「画面切り替えのタイミング」
  ⇒「クリック時」から「自動的に切り替え」に変更
   その後任意の時間を設定
   (シートの選択を解除してから個別のシートの時間を変更することも可能)
   
これでOK。

RESTとは何か。

簡単に言うと「RESTとは、Representational State Transferの略でソフトウェアアーキテクチャのスタイルのひとつ」しかしこれがまたややこしくしている。
なぜかというとよくセットで語られるSOAPは仕様。それに対してRestはアーキテクチャ。なのでRESTは細かいところを定めているわけじゃなくて
多種多様なものがRESTと呼ばれてしまっている。

RESTは、初めはアーキテクチャの原則と制約の集まり(後述)を指していたが、次第に、XMLやHTTPを使った簡易なウェブベースのインターフェイスのうち、WebサービスSOAPプロトコルのような MEP(Message Exchange Pattern; SOAPノード相互のメッセージ交換のパターンを確立するための雛型)ベースの特別な抽象化をしないもののことを、大まかに意味する用語として使われるようになった

REST - Wikipedia

なのでRESTといわれたら相手がどのようなRESTをイメージしているのか確認するといい。
RESTの定義には色々あるがマーチンファウラーが定義しているRESTful成熟度の3レベルモデルが相手の理解を知るにはよい指標となるとおもう。
martinfowler.com

  • Level 0 Plain Old XML(昔ながらの単純にXMLを返すやり方)
  • Level 1 URLでリソースを表すようにする(リソースを動詞でなく名詞で表す)
  • Level 2 HTTPメソッドGET, POST, PUT, DELETE等を正しく使い分ける
  • Level 3 レスポンスの中に関連するリンクを含める

Level3はNetflixAPIとか、API自体がハイパーメディアとして動作するようなもの。ほぼ見かけない。
今世界で言われている大半のAPIはLevel2。Level1だとWebで公開するとハテブとかでちょっとけちつけられる可能性がある。
でも上記にあってなくても使いやすければLevel1でも悪くないとおもうよ。だってちゃんとしたRestで考えると色々使いにくいから。。。

そんな使いにくさもありDropBoxがRestのサポートをやめたり、*1
GoogleAPIもHTTP2ではgRPCを主軸においてたり、今後Restから次のステージが模索されている。
とはいえ本家RESTも大事なのでちゃん仕様を統一しようてことでOpen API Initiative*2がSwaggerベースで仕様統一を検討し始めている。

RESTが誕生して16年。これからも目が離せませんね

Ubuntu にsar(sysstat)をインストールする。

性能がちょっとおそいなとか、IOどうなってるんだろうなとおもったらsysstatが便利です。
かんたんなものはtopとか眺めているといいですが、ちょっときがきいたものをみたければ迷わずsysstatを使いましょう。

Ubuntuにはデフォでは入っていないのでインストールします。

インストール&設定

$ sudo apt-get install sysstat

設定ファイルを書き換えて性能取得を有効にします

$ sudo vi /etc/default/sysstat
ENABLED="false"
  ↓
ENABLED="true"

サービス起動します

$ sudo /etc/init.d/sysstat start
 * Starting the system activity data collector sadc                                        [ OK ]
$

デフォルトだとCronでこんな感じに動きます。

$ cat /etc/cron.d/sysstat
# The first element of the path is a directory where the debian-sa1
# script is located
PATH=/usr/lib/sysstat:/usr/sbin:/usr/sbin:/usr/bin:/sbin:/bin

# Activity reports every 10 minutes everyday
5-55/10 * * * * root command -v debian-sa1 > /dev/null && debian-sa1 1 1

# Additional run at 23:59 to rotate the statistics file
59 23 * * * root command -v debian-sa1 > /dev/null && debian-sa1 60 2

つまりXX時05分から10分毎にログをとって、23時59分にログファイルをローテートする為にもう一度実行しています。
ログはこんな感じでファイルで出力されます。

$ ls  -l /var/log/sysstat/
total 12
-rw-r--r-- 1 root root 11756 Oct  3 03:15 sa03

ちなみにファイル名ですが、「saDD」という形式で「DD」部分に日付が入ります。
パラメータをいじるとYYYYMMDDとかにも出来ます。詳しくは内部で使われているsadcコマンドのマニュアルを見ましょう

       The  standard  system  activity  daily  data  file is named saDD unless
       option -D is used, in which case its name  is  saYYYYMMDD,  where  YYYY
       stands  for  the  current year, MM for the current month and DD for the
       current day.  By default it is located in the  /var/log/sysstat  direc‐
       tory.

参照してみる

CPU情報を表示してみます(sa03のところは見たいファイルにあわせて変更する)

$ sar -f /var/log/sysstat/sa03 -P ALL
Linux 4.4.0-36-generic (ubuntu-1404)    10/03/2016      _x86_64_        (2 CPU)

02:41:01 AM       LINUX RESTART

02:45:01 AM     CPU     %user     %nice   %system   %iowait    %steal     %idle
02:55:01 AM     all      0.05      0.00      0.09      0.00      0.00     99.87
02:55:01 AM       0      0.04      0.00      0.10      0.00      0.00     99.86
02:55:01 AM       1      0.05      0.00      0.07      0.00      0.00     99.87

02:55:01 AM     CPU     %user     %nice   %system   %iowait    %steal     %idle
03:05:01 AM     all      0.05      0.00      0.07      0.00      0.00     99.89
03:05:01 AM       0      0.03      0.00      0.08      0.00      0.00     99.89
03:05:01 AM       1      0.06      0.00      0.06      0.00      0.00     99.89

03:05:01 AM     CPU     %user     %nice   %system   %iowait    %steal     %idle
03:15:01 AM     all      0.04      0.00      0.05      0.00      0.00     99.91
03:15:01 AM       0      0.02      0.00      0.06      0.00      0.00     99.91
03:15:01 AM       1      0.05      0.00      0.04      0.00      0.00     99.91

Average:        CPU     %user     %nice   %system   %iowait    %steal     %idle
Average:        all      0.04      0.00      0.07      0.00      0.00     99.89
Average:          0      0.03      0.00      0.08      0.00      0.00     99.89
Average:          1      0.05      0.00      0.06      0.00      0.00     99.89

ロードアベレージをみるのはこんな感じ

$ sar -f /var/log/sysstat/sa03 -q

メモリやネットワークなども見れます。詳しくは以下等を参照しましょう。
Linux - sarコマンドについて - Qiita

Ksarで見やすく表示

コマンドで仔細に見るのもいいですが、GUIで見やすく見るほうがなにかと便利なのでKSARでみてみましょう。
https://sourceforge.net/projects/ksar/files/beta/
から、「kSar-5.1.0-beta4.zip」をダウンロード

$ export LC_ALL=C && export S_TIME_FORMAT=ISO

をうって言語と時間設定を直してから

$ sar  -A 10 300 > performance.txt

でいけます。


詳しい使い方は以下にまとめてあります。
garapon.hatenablog.com

最新のHyperLederFabricをProxy環境下でビルドする

2016/06にv0.5-developer-previewが出たfabricですが、現在も日々コードが書き換わりまくっています。
今日落とすと0.7.0がおちてきます。直近のマイルストンは以下のとおり
・2016/10 :アルファ版
・2017/01 :v0.1-ベータ版
・2017/03 :v1.0正式版

製品ソースも変わっていますし、開発環境の構築の中の仕組みも結構変わっているようです。
最新版(0.7.0)をProxy環境下でビルドしたら結構はまったので対処法を記載しておきます。
※Porxyが必要ない環境であれば以下手順でビルドするのは変わっていません。
garapon.hatenablog.com


各種準備

事前準備、fabricのソースのDLまでは以下手順に従い進めましょう。
Windows上にhyperledger/fabricを環境構築する。 - 自分の仕事を憎むには人生は余りにも短い

Vagrantファイルの書き換え

fabric\devenv\Vagrantfile
を修正してProxy設定を入れます。L33の下にこんな風書きます。

Vagrant.configure('2') do |config|
if Vagrant.has_plugin?("vagrant-proxyconf")
    config.proxy.http = "http://proxyserver:8080/"
    config.proxy.https = "http://proxyserver:8080/"
    config.proxy.no_proxy = "localhost,127.0.0.1"
end

VM起動

cd %GOPATH%\src\github.com\hyperledger\fabric\devenv\
vagrant up

upが終わったらprovisionしていきましょう。

vagrant up --provision

DockerImageのビルド準備

DockerImageをこれからビルドしていくのですが、その中でProxy設定が通らないものがありますので
先にProxy設定をいれていきます。

fabric\images\javaenv\Dockerfile.in
L3とL9を書き換えます。WgetcurlにProxyを設定します

L3:RUN wget http://services.gradle.org/distributions/gradle-2.12-bin.zip -P /tmp --quiet
L9:  && curl -fsSL http://apache.osuosl.org/maven/maven-3/$MAVEN_VERSION/binaries/apache-maven-$MAVEN

L3:RUN wget -e HTTP_PROXY=http://proxyserver:8080/ http://services.gradle.org/distributions/gradle-2.12-bin.zip -P /tmp --quiet
L9:  && curl -fsSL -x proxyserver:8080 http://apache.osuosl.org/maven/maven-3/$MAVEN_VERSION/binaries/apache-maven-$MAVEN

とします。

fabric\core\chaincode\shim\java\javabuild.sh
を書き換えます。GradleにProxyをとおします。

gradle -q -b ${PARENTDIR}/core/chaincode/shim/java/build.gradle build

これが

gradle -Dhttp.proxyHost=proxyserver -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxyserver -Dhttps.proxyPort=8080 -q -b ${PARENTDIR}/core/chaincode/shim/java/build.gradle build

こうなる


これでOK。
おわったら立ち上がったLinuxにログインして作業を進めます。
garapon.hatenablog.com

DockerImageのビルド

さっそくビルドしましょう。

$ cd $GOPATH/src/github.com/hyperledger/fabric
$ make peer-image
$ make membersrvc-image

確認します。

$ docker images
REPOSITORY                      TAG                             IMAGE ID            CREATED             SIZE
hyperledger/fabric-membersrvc   latest                          6e0ad0ce5870        2 hours ago         1.44 GB
hyperledger/fabric-membersrvc   x86_64-0.7.0-snapshot-42ca84b   6e0ad0ce5870        2 hours ago         1.44 GB
hyperledger/fabric-peer         latest                          6323f96d118c        3 hours ago         1.446 GB
hyperledger/fabric-peer         x86_64-0.7.0-snapshot-42ca84b   6323f96d118c        3 hours ago         1.446 GB
hyperledger/fabric-javaenv      latest                          484a2c1d472e        3 hours ago         791 MB
hyperledger/fabric-javaenv      x86_64-0.7.0-snapshot-42ca84b   484a2c1d472e        3 hours ago         791 MB
hyperledger/fabric-ccenv        latest                          12e4b7c10976        3 hours ago         1.439 GB
hyperledger/fabric-ccenv        x86_64-0.7.0-snapshot-42ca84b   12e4b7c10976        3 hours ago         1.439 GB
hyperledger/fabric-src          latest                          8b4953ed2add        3 hours ago         1.418 GB
hyperledger/fabric-src          x86_64-0.7.0-snapshot-42ca84b   8b4953ed2add        3 hours ago         1.418 GB

いっぱい出来ましたね。

fabricネットワークの起動

さてきどうしましょう。起動する前に
fabric\bddtests\bdd-docker\docker-compose-4-consensus-batch.yml
を修正します。
L18を

    - 7050:7050

と書き直しましょう。これを7050にしておくことでVagrantを起動している外からアクセス可能になります。

書き直したら起動!

$ cd cd $GOPATH/src/github.com/hyperledger/fabric/bddtests/bdd-docker
$ docker-compose -f docker-compose-4-consensus-batch.yml up --force-recreate -d

確認してみると

$ docker ps
CONTAINER ID        IMAGE                           COMMAND                  CREATED             STATUS              PORTS                    NAMES
a8e67ef73d7c        hyperledger/fabric-peer         "sh -c 'exec $GOPATH/"   2 hours ago         Up 2 hours                                   bdddocker_vp2_1
215ecca8e1a3        hyperledger/fabric-peer         "sh -c 'exec $GOPATH/"   2 hours ago         Up 2 hours                                   bdddocker_vp1_1
83688e10e2a3        hyperledger/fabric-peer         "sh -c 'exec $GOPATH/"   2 hours ago         Up 2 hours                                   bdddocker_vp3_1
2e4ba2618554        hyperledger/fabric-peer         "sh -c 'exec $GOPATH/"   2 hours ago         Up 2 hours          0.0.0.0:7050->7050/tcp   bdddocker_vp0_1
d94ead61d86d        hyperledger/fabric-membersrvc   "membersrvc"             2 hours ago         Up 2 hours                                   bdddocker_membersrvc0_1

動いてますね。

やれやれ