in-house-swagger / in-house-swagger Goto Github PK

in-house swagger-tools server

Home Page: https://in-house-swagger.github.io/in-house-swagger/index.html

License: Apache License 2.0

Shell 88.32% Groovy 0.50% HTML 11.18%

swagger swagger2 swagger-codegen swagger-generator swagger-ui swagger-editor jetty groovy swagger-spec-mgr openapi-specification

in-house-swagger's Introduction

in-house-swagger

in-house swagger-tools

in-house-swagger's People

Contributors

Stargazers

Watchers

in-house-swagger's Issues

ストーリー

利用者として
ブランチ戦略に従ってSpecを更新するために、
editorからブランチを管理できる。

背景・経緯

gitを利用する場合、git flowやgithub flow などのブランチ戦略で運用するのが定石なので
画面からブランチを操作できるようにしたい。

受け入れ条件

editorから、ブランチを作成できること
editorから、ブランチをリネームできること
editorから、ブランチを削除できること
editorから、ブランチをマージできること
editorから、ブランチを切り替えられること

ストーリー

利用者として
チームで開発するために、
editorからコミットユーザを管理できる。

背景・経緯

チームで開発する場合、誰がSpecを更新したのか把握したいので
画面からコミットユーザを操作できるようにしたい。

受け入れ条件

editorから、コミットユーザを作成できること
editorから、コミットユーザを削除できること
editorから、コミットユーザを切り替えられること

ストーリー

利用者として
Spec管理で発生したエラーを把握するために、
操作と紐付けたメッセージを確認できる。

背景・経緯

現状の spec-mgrから返されたエラーメッセージは
spec-mgrとしての操作に紐付いたメッセージになっている。
※重複した specId を POST すると「すでにディレクトリが存在する」など

このまま、画面に表示しても利用者としてはわからないので
「すでにSpecが存在する」などにマッピングしたい。

受け入れ条件

editorで通知されるエラーメッセージが、利用者から理解できること

対応詳細

spec-mgr側で、webapi responseにmessageCodeを追加

{
  payload: {}
  _errors: {
    empty: false
    list: [
      {
        propertyKey: Specification
        code: dir.alreadyExist
        message: ディレクトリが既に存在します。対象ディレクトリ：...
    ]
  }
}

spec-mgr側で、DELETEのerror発生時にresponse bodyを返すように変更
　現状は、DELETEのレスポンスボディはないので、エラー時も400系が返されるだけなので。
editor側で、messageCodeから、自分のメッセージマッピングする処理を追加
in-house-swaggerで、更新版を取り込み

マニュアルのinstallコマンドで、bintrayからダウンロードできない

事象

マニュアルのinstallコマンドをコピー&ペーストで実行しても、ダウンロードできない。

バージョン

0.5.1

実行環境

macOS HighSierra

ログ

$ curl \
>   --request GET \
>   --url "${download_url}" \
>   --output "${archive_name}"
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:--  0:00:01 --:--:--     0
$ ls -l

対応

--location オプションが必要な様子。

$ curl \
>   --verbose \
>   --request GET \
>   --location \
>   --url "${download_url}" \
>   --output "${archive_name}"
Note: Unnecessary use of -X or --request, GET is already inferred.
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0*   Trying 108.168.243.150...
* TCP_NODELAY set
* Connected to dl.bintray.com (108.168.243.150) port 443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
* successfully set certificate verify locations:
*   CAfile: /etc/ssl/cert.pem
  CApath: none
* TLSv1.2 (OUT), TLS handshake, Client hello (1):
} [512 bytes data]
* TLSv1.2 (IN), TLS handshake, Server hello (2):
{ [106 bytes data]
* NPN, negotiated HTTP1.1
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0* TLSv1.2 (IN), TLS handshake, Certificate (11):
{ [3591 bytes data]
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
{ [333 bytes data]
* TLSv1.2 (IN), TLS handshake, Server finished (14):
{ [4 bytes data]
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
} [70 bytes data]
* TLSv1.2 (OUT), TLS change cipher, Client hello (1):
} [1 bytes data]
* TLSv1.2 (OUT), TLS handshake, Unknown (67):
} [36 bytes data]
* TLSv1.2 (OUT), TLS handshake, Finished (20):
} [16 bytes data]
* TLSv1.2 (IN), TLS change cipher, Client hello (1):
{ [1 bytes data]
* TLSv1.2 (IN), TLS handshake, Finished (20):
{ [16 bytes data]
* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256
* ALPN, server did not agree to a protocol
* Server certificate:
*  subject: CN=*.bintray.com
*  start date: Nov  9 00:00:00 2017 GMT
*  expire date: Nov  9 23:59:59 2019 GMT
*  subjectAltName: host "dl.bintray.com" matched cert's "*.bintray.com"
*  issuer: C=US; O=GeoTrust Inc.; OU=Domain Validated SSL; CN=GeoTrust DV SSL CA - G3
*  SSL certificate verify ok.
> GET /in-house-swagger/in-house-swagger/in-house-swagger-0.5.1.tar.gz HTTP/1.1
> Host: dl.bintray.com
> User-Agent: curl/7.54.0
> Accept: */*
> 
< HTTP/1.1 200 OK
< Server: nginx
< Date: Tue, 10 Apr 2018 00:27:09 GMT
< Content-Type: application/gzip
< Content-Length: 30183
< Connection: keep-alive
< Content-Disposition: attachment; filename="in-house-swagger-0.5.1.tar.gz"
< Last-Modified: Mon, 09 Apr 2018 00:53:47 GMT
< Cache-Control: max-age=30, must-revalidate
< Accept-Ranges: none
< ETag: e1c3c06c8440839daa3b0af5a5c8c831951505b406f8a098c131007eb3fc7c46
< X-Checksum-Sha1: c25ce2a660138aed96c8943ab8f849227c21beb5
< X-Checksum-Sha2: e1c3c06c8440839daa3b0af5a5c8c831951505b406f8a098c131007eb3fc7c46
< 
{ [850 bytes data]
100 30183  100 30183    0     0  20251      0  0:00:01  0:00:01 --:--:-- 20257
* Connection #0 to host dl.bintray.com left intact
$ ls -l
total 163936
-rw-r--r-- 1 OWNER GROUP     30183 2018-04-10 09:27:09 in-house-swagger-0.5.1.tar.gz

ストーリー

利用者として
便利な機能を利用するために、
swagger-editor, ui でreleaseされた最新のバージョンを利用できる。

背景・経緯

OAS3 が公開された。
公開直後に確認したところ、code-genがOAS3に対応していなかったが
editor, uiはすでに対応済みの様子。

editorの対応内容だけ見ても、オートコンプリートなど便利そうな機能が入っていたので
OAS2の定義で動くか確認して、可能であれば取り込みたい。
※Generatorは、別対応もあるので次のイテレーションで対応。

対応詳細

forkしたswagger-editorでin-houseブランチを最新化。アーカイブ公開。
forkしたswagger-uiでin-houseブランチを最新化。アーカイブ公開。
in-house-swagger で最新版を取り込み。

editorからgeneratorのoptionを指定したい

ストーリー

in-house-swaggerでAPIを公開する利用者として
公開したAPIの利用者に、client sourceを生成してもらうために、
editorから、languageごとのoptionを指定できる。

背景・経緯

generatorのAPIで /api/server/{lang} or /api/client/{lang} のGETで
langが対応しているOPTIONが返ってくる。

本格的に実現するならswagger hubに倣って

editorに専用のpopupを用意
langを選択して、対応しているoptionの入力フォームを生成
入力内容を保存して、langに合わせたoptionで生成リクエスト
※swagger hubの場合、api proxyがいて、optionを保存しているっぽい

option指定しないと、デフォルト値で生成されてしまうので
editorからの生成を利用するなら、option指定は必須。
どこまでやるか。。。

まずは「指定できる状況」を用意しておきたい。

受け入れ条件

language ごとにoptionを指定できること
各langのoptionの初回作成時は、languageに合わせたスキャフォルドが自動設定されること
設定したoptionでgenerateできること

対応詳細

editorにlangごとのgenerate optionを保存できる画面を用意
- popupを追加
  - langを選択
  - 保存されていない場合
    - langのoptionをGET
    - 空のoption jsonを、popup内エディタに表示
    - 新規保存
  - 保存されている場合
    - 保存内容を、popup内エディタに表示
    - 上書き保存
- 生成リクエスト時
  - 保存内容を、postのentity bodyに追加
    なければ空オブジェクト

editorでspec-mgrを利用してspecificationを管理したい

ストーリー

利用者として
定義を管理するために、
editorから定義を追加、更新、削除、指定した定義を開くことができる。

背景・経緯

spec-mgrを取り込んだが、連携は editor の importURLのみ。
追加時は、editorで編集後、spec-mgr/ui に定義内容を貼り付けてPOST。
更新時は、editorで編集後、spec-mgr/ui に定義内容を貼り付けてPUT。
削除時は、spec-mgr/ui でDELETE。
操作がわかりにくい。

受け入れ条件

後述の操作は、spec-mgrのデフォルトユーザで管理するspecに対して実行されること
追加時は、editorの save as ボタンで、名前を指定して保存できること
更新時は、editorの open ボタンで一覧から選択して開き、save ボタンで上書き保存できること
削除時は、editorの delete ボタンで一覧から選択して削除できること

対応詳細

forkしたswagger-editorのin-houseブランチで、OAS3版のtopbarソースを更新
topbar更新後のソースで配布アーカイブを作成
in-house-swaggerのmoduleを更新

ストーリー

開発者として
ドキュメント精度の向上をするために、
ツールによる自動チェックができる。

背景・経緯

redpen＋travis ciを導入する

受け入れ条件

push時、redpenによるチェックが行われること

対応詳細

redpenを導入する
travis ci環境で、redpenが動作するよう設定する

ストーリー

利用者として
最新のOAS使用を利用するために、
OAS2 / 3 を使い分けできる。

背景・経緯

OAS3 がリリースされたが、codegenが正式対応されていない。
codegenが正式リリースされ次第で、対応を載せたい。

受け入れ条件

OAS2 / 3 を設定で切り替えできること
- 可能であれば、動的に切り替えたい。最低限設定で切り替えられること。
workflow全体で OAS3 を利用できること
- 対応済み
  - swagger-ui: 導入済み
  - swagger-editor: 導入済み
- 未対応
  - swagger-codegen-cli
  - swagger-generator
- 動向を確認中
  - swagger2markup
  - swagger-spec-mgr

対応詳細

swagger-spec-mgr対応メモ
多分、分割設定を切り替えるだけで済むはず。

ストーリー

利用者として
Docker経由でサービス利用するために、
サイズの小さいdockerイメージを生成できる。

背景・経緯

・debianベースのopenjdkイメージは、in-house-swaggerに
必要ないパッケージも含まれているため、イメージサイズが大きい。
alpine linuxベースとすることで、イメージサイズ縮小をはかる。
・VERSIONファイルよりタグを設定する

受け入れ条件

docker-run.sh updateにより、イメージ生成できること
docker-run.sh startにより、生成したイメージを実行できること
docker-run.sh stopにより、実行したイメージを停止できること

対応詳細

DockerFile 修正（debianベース → alpineベース）
docker-run.sh 修正（タグ設定）

ストーリー

利用者として
細い回線で利用を開始するために、
install時のアーカイブダウンロードをresume/retry できる。

背景・経緯

細い回線でinstallを実行すると、容量の大きなアーカイブのダウンロードがエラー終了することがある。
途中までダウンロードした結果から、続きをダウンロードできるようにしたい。
中断しているので、正しくダウンロードできたか後で確認する仕組みも必要。

受け入れ条件

installがダウンロードでエラー終了した場合、リトライできること
リトライでは、途中までダウンロードした結果の続きから再開できること
md5 | sha1|asc(pgp) でダウンロード結果が壊れていないことを保証していること

対応詳細

bin/install local.gracefull_download に再開の考慮を追加
bin/install local.download で再開オプションを追加
ファイルが存在する場合、curlに --continue-at オプションを付ける。
bin/install local.gracefull_download で md5 | sha1 | asc(pgp) の確認を追加
基本は md5sum を想定(/tmpに.md5ファイルを作成し、md5sum -c でチェック)
bintrayは asc とする。指定は bintray:プロジェクト名
config/project.propertiesにCHECKSUM_xxxを追加。定義なしはチェックしない。

ストーリー

利用者として
起動時のトラブルを回避するために、
デフォルトの起動ポート9700,9701で起動できる。

背景・経緯

ポート8080,10000 等の場合、一般的な他サービスとポートが競合し、起動できない可能性がある。
ポートはまとめを見てみた感じだと 9700 とかが手頃ですかね。
複数台立てる時に、連番使いたいとかはあると思うので、きりの良いところでf(^_^;
https://ja.wikipedia.org/wiki/TCP%E3%82%84UDP%E3%81%AB%E3%81%8A%E3%81%91%E3%82%8B%E3%83%9D%E3%83%BC%E3%83%88%E7%95%AA%E5%8F%B7%E3%81%AE%E4%B8%80%E8%A6%A7

受け入れ条件

デフォルトポートは9700,9701で起動できること
project.propertiesの設定で変更できること

対応詳細

project.propertiesのSERVER_PORTを9700に変更

dockerイメージを生成したい

ストーリー

利用者として
Docker経由でサービス利用するために、
dockerイメージを生成できる。

背景・経緯

swagger uiなどでは、DockerFileを用意しており、利用者がdockerイメージを生成できるようにしている。in-house-swaggerでも同様に、DockerFile＋起動用シェルの仕掛けを用意する。
dockerを利用するメリットとしては、同サーバ上でjavaなどのバージョン競合等考慮不要となる

受け入れ条件

docker-run.sh updateにより、イメージ生成できること
docker-run.sh startにより、生成したイメージを実行できること
docker-run.sh stopにより、実行したイメージを停止できること

対応詳細

DockerFile 作成
docker-run.sh 作成
.dockerignore を作成（distは対象外とする）

バインドするホストを設定したい

ストーリー

利用者として
他システムから接続するために、
バインドするホストを設定できる。

背景・経緯

複数IPを持っているマシン上で動かす場合など、明示的にバインドホストを指定したいことがありそう。

受け入れ条件

バインドするホストを設定できること
spec-mgrにも同じホストが設定されること
デフォルトは設定なしで起動すること

対応詳細

bin/server start で jetty起動時にバインドホストの環境変数の付け外しを考慮
jetty.http.host
http://www.eclipse.org/jetty/documentation/9.4.x/configuring-connectors.html
デフォルトの起動ポートも合わせて 10000 に変更
spec-mgr にバインドホストの環境変数を引き継ぐ
server.address
https://stackoverflow.com/questions/23946369/how-to-configure-embedded-tomcat-integrated-with-spring-to-listen-requests-to-ip

課題

jettyの場合、jetty.http.host=指定なしだと、127.0.0.1, localhost, 自IP にアクセスできる
が
spring bootの場合、server.address=空文字だと、127.0.0.1, localhostはOKだが、自IPはNG
application.ymlで server.addressの定義自体を付け外ししないといけないかも。。。

OASから静的なドキュメントを生成する機能が欲しい

ストーリー

利用者として
ステークホルダーにドキュメントを提供するために、
OASをadocに変換できる。

背景・経緯

swagger-uiで提供するのは、server側のテストorスタブ環境がセットなので
ステークホルダー向けには、静的なドキュメントの提供が必要。

asciidoctorを利用すればadocから、html, epub, pdfなどにも変換できる。
ドキュメントの形式は利用者の状況に合わせて選択できるようにしたいが
yaml, jsonのままでは、変換に必ず一手間必要なので、adocまでの変換は、機能に含めておきたい。

受け入れ条件

コマンドラインから spec-mgrで管理しているOASをadocとして出力できること

対応詳細

swagger2markupをmoduleに組み込む
https://github.com/Swagger2Markup/swagger2markup
spec-mgrからOASをDLして、adocに変換するスクリプトを用意

ドキュメント整理

ストーリー

利用者として
概要、利用方法を把握するために、
webでドキュメントを参照できる。

受け入れ条件

GitHub Pagesで、概要、マニュアルが参照できること
readme.mdから、リンクを辿ることができること

対応詳細

masterブランチのdocs公開スタイル
図解
- overview
- system architecture
- workflow
adoc -> asciidoctor でドキュメントもsourceと一緒にバージョン管理
reveal.js で概要説明

swaggerのvalidatorがin-house化できていない

swagger-generatorをin-houseで起動したい
【事象】
画面最下部のvalidatorがうまく動作してない ERROR {...}
https://online.swagger.io/validator/debug?url=/api/swagger.json

swagger-ui環境(in-house化保留中)だと以下で動作して VALID {...}
https://online.swagger.io/validator/debug?url=http://petstore.swagger.io/api/swagger.json

【原因】
validator からurlを参照できないため

【対策】
https://online.swagger.io/validator もin-houseに持ってくる
https://github.com/swagger-api/validator-badge
もしくは消しちゃう
http://qiita.com/utisam/items/61e7551504bcf80854a5

リリース手順を自動化したい

ストーリー

開発者として
作業を軽減するために、
リリース時の作業を自動実行できる。

背景・経緯

現状の手順は下記。抜け漏れが発生しそうなので自動化しておきたい。
配布アーカイブをGitHubで公開しているが、容量に1GBあたりの制限があったと思うので、bintrayに移しておきたい。

リリース作業
1. バージョンからSNAPSHOTを削除
2. document build
3. product build
4. push
5. tag
6. 配布アーカイブ添付
リリース後作業
1. バージョンを、マイナーバージョンをインクリメント + SNAPSHOT に更新
2. push

受け入れ条件

プルリが揃った時点で起動できること
手順をアトミックに実施できること
bintrayから配布アーカイブをダウンロードできること
- md5 or sha1 or gpg でダウンロードを検証できること

swagger-spec-mgrをmodulesに追加

ストーリー

利用者として
swagger.yamlをバージョン管理するために、
swagger-spec-mgrを利用できる。

背景・経緯

swagger-editor で編集したswagger.yamlは、browserのlocalstorageに保存されるだけ
importする機能はあるが、swagger.yamlをどこで管理するかは任意なので
デフォルトの管理場所を用意する。

swagger.yamlは本格的に利用すると、大きなファイルになってしまう。
定義内容を構造体ごとに分割して、git管理したい。
local repository のみ、remoteあり（github/gitlabなど）は設定で切り替えたい。

受け入れ条件

他モジュールと同様に installで自動ダウンロードできること
他モジュールと同様に server で起動/停止を制御できること

移転先リポジトリからアーカイブをダウンロードしたい

背景・経緯

開発者向けに管理しやすいようにorganizationにリポジトリを移転した。
各moduleの配布アーカイブのダウンロードURLも変更されたので、合わせて変更する。

構築、設定変更をシンプルにしたい

ストーリー

利用者として
利用開始時に何をしているのかを把握するために、
シンプルな手順で設定できる。

背景・経緯

ドキュメントを用意しようとしたが、意図がわかりにくい手順が必要なので
シンプルになるように整理したい。

対応詳細

spec-mgr起動ポート
spec-mgr側はin-house-swagger +1
editorがデフォルトでつなぐ先が渡せないので。
1. spec-mgr
  - ポートの指定を、環境変数優先に変更
  - application.yamlのcontextPathを環境変数指定に変更
  - 環境変数側はデフォルトで空文字
2. editor
  接続先spec-mgrのデフォルトを
  自IP:自ポート + 1 に変更
```
let defaultSpecMgrHostname = window.location.hostname
let defaultSpecMgrPort = eval(window.location.port) + 1
curSpecMgr: "http://" + 
    defaultSpecMgrHostname + ":" + 
    defaultSpecMgrPort
```
1. in-house-swagger
  spec-mgr起動ポートを自ポート + 1 に設定して起動
```
SPECMGR_PORT=$((${SERVER_PORT} + 1))
```
Jettyインストール
jettyのインストール時に
jetty/etc/jetty.conf に console-capture.xml の指定を追加
※これをやっておかないとwebappのログが出ない。。。
generatorをwar展開インストールに変更
ログレベルの変更など設定変更できるようにしておきたい。
bin/server start
- spec-mgrの起動時にport表示
- 起動順を spec-mgr -> jetty に変更
- jar形式 custom generator jarをシンボリックリンクでgenerator/WEB-INF/lib に同期
インストール手順
spec-mgrのインストール時にデフォルトユーザを作成しているが
git remote repoを利用する場合は、削除 & 再作成が必要。
※git remote repoありの場合、意味の分からない手順。。。
1. spec-mgr
  - デフォルトユーザ作成・削除をコマンドで実装
    →bin/git/clone.sh がユーザ追加相当なので、forceオプションの追加で再作成に対応。
2. in-house-swagger
  - bin/install デフォルトユーザ追加を廃止

手順イメージ
- install
  1. bin/install
  2. （module/swagger-spec-mgr/config 変更）
  3. module/swagger-spec-mgr/bin/git/clone.sh
    → bin/server start の時には使える状態が整っている
- server control
  - start
  - stop
  - restart
- generate
  - template指定なし
    editorから
  - template指定あり
    cliから
  - groovy custom generator
    cliから