in-house-swagger 0.5.2

1. Overview

1.1. Feature

swagger tools（editor, generator, ui, validator, codegen-cli）, swagger2markup, spec-mgr を一括インストール
generator、codegen-cli のカスタマイズ内容をconfigディレクトリで一元管理
editorから、generator optionを指定してリソースを自動生成
Open API Specification（OAS）を、json-refsで分割管理
Open API Specification（OAS）を、Git管理（branch, tag, commit user, commit message）

1.2. Workflow

1.3. Architecture

1.4. Licenses

product	license	message
in-house-swagger	Apache License 2.0	-
swagger-editor	Apache License 2.0	changes
swagger-ui	Apache License 2.0	changes
swagger-codegen	Apache License 2.0	-
swagger2markup	Apache License 2.0	-
swagger-spec-mgr	Apache License 2.0	-
Smashicons	Flaticon Basic License	image icons designed by Smashicons from Flaticon

product

license

message

in-house-swagger

swagger-editor

swagger-ui

swagger-codegen

swagger2markup

swagger-spec-mgr

Smashicons

Flaticon Basic License

image icons designed by Smashicons from Flaticon

2. Installation

2.1. Target OS

RHEL-derivatives / Fedora
Debian / Ubuntu
OSX

2.2. Dependencies

command	version
curl	-
md5sum	-
sha1sum	-
gpg	-
git	1.7 or later
java	jre 8 or later

command

version

curl

md5sum

sha1sum

gpg

git

1.7 or later

java

jre 8 or later

2.3. Getting Started

バージョンを選択
- 最新安定版バージョンの場合: version="0.5.2"
ダウンロード

# アーカイブを選択
#   通常版 ※installコマンド実行時にモジュールをダウンロード
archive_name="in-house-swagger-${version}.tar.gz"
#   モジュール同梱版
archive_name="in-house-swagger-with-depends-${version}.tar.gz"

# ダウンロードURL
url_base="https://dl.bintray.com/in-house-swagger/in-house-swagger"
download_url="${url_base}/${archive_name}"

# ダウンロード
curl \
  --request GET \
  --location \
  --url "${download_url}" \
  --output "${archive_name}"

インストール

tar xf "${archive_name}"
cd "$(basename ${archive_name} .tar.gz)/"
bin/install

gitリモートリポジトリを利用する場合のみ実施

# リモートリポジトリURLを設定
{
  echo "export GIT_REMOTE_REPOSITORY_URL=${YOUR_REPO_URL}"
} >> module/swagger-spec-mgr/config/swagger-spec-mgr.properties

# 接続情報の暗号化
{
  echo "GIT_ACCESS_USER=${YOUR_REPO_USER}"
  echo "GIT_ACCESS_PASSWORD=${YOUR_REPO_PASSWORD}"
} > module/swagger-spec-mgr/config/access_info
module/swagger-spec-mgr/bin/mainte/encrypt_access_info.sh

デフォルトのgitコミットユーザを登録

module/swagger-spec-mgr/bin/git/clone.sh

Server起動

bin/server start

swagger-editor URL
- http://localhost:9700/editor
swagger-ui URL
- http://localhost:9700/ui
spec-mgr URL
- http://localhost:9701

3. Configuration

3.1. config/

3.1.1. project.properties

起動ポートを変更する

# default: 9700
# spec-mgr port: SERVER_PORT + 1
SERVER_PORT=9700

jettyの起動パラメータを変更する

# jetty起動引数
JETTY_ARGS="jetty.http.port=${SERVER_PORT}"

利用ツールのバージョンを変更する

# ダウンロードURL
DOWNLOAD_URL_JETTY="http://central.maven.org/maven2/org/eclipse/jetty/jetty-distribution/9.4.6.v20170531/jetty-distribution-9.4.6.v20170531.tar.gz"
DOWNLOAD_URL_GROOVY="https://dl.bintray.com/groovy/maven/apache-groovy-binary-2.4.12.zip"
DOWNLOAD_URL_CODEGEN_CLI="http://central.maven.org/maven2/io/swagger/swagger-codegen-cli/2.2.3/swagger-codegen-cli-2.2.3.jar"
 :

利用ツールのダウンロード検証ハッシュを変更する

# ダウンロード検証(md5/sha1/bintray:project名/なし)
CHECKSUM_JETTY=md5
CHECKSUM_GROOVY=bintray:groovy
CHECKSUM_CODEGEN_CLI=md5
 :

3.2. module/swagger-spec-mgr/config/

3.2.1. swagger-spec-mgr.properties

デフォルトのコミット設定を変更する

export SCM_DEFAULT_USER="spec-mgr"
export SCM_DEFAULT_EMAIL="spec-mgr@example.com"
export SCM_DEFAULT_COMMIT_MESSAGE="update API specifications."

Specの管理ディレクトリを変更する

# リポジトリルートからのSpec管理ディレクトリ相対パス
export RELDIR_SPECS="docs/design/swagger"

3.2.2. application.yml

Specの分割除外設定を変更する

  # 分割除外パス正規表現リスト
  splitIgnoreRegexList:
  - "/info/.*"
  - "/tags/.*"
  - "/schemas/.*"
  - "/securityDefinitions/.*"
  - "/paths/.*/consumes"
  - "/paths/.*/parameters"
  - "/paths/.*/produces"
  - "/paths/.*/responses"
  - "/paths/.*/tags"
  - "/paths/.*/security"

4. Manual

4.1. Web

4.1.1. Server Control

起動

bin/server start

停止

bin/server stop

再起動

bin/server restart

4.1.2. Swagger Editor

デフォルト設定の場合、 http://localhost:9700/editor でアクセスできます。

Specの管理

開く

File > Open をクリック
SpecID を選択
Open ボタンをクリック

新規保存

File > Save as… をクリック
SpecID を入力
Create ボタンをクリック

上書き保存

File > Save をクリック

削除

File > Delete をクリック
SpecID を選択
Delete ボタンをクリック

URLを編集画面にimport

File > Import URL をクリック
Specの公開URLを入力
Import ボタンをクリック

ローカルファイルを編集画面にimport

File > Import File をクリック
ファイルを選択
Import ボタンをクリック

編集内容をyamlフォーマットでダウンロード

File > Download YAML をクリック

編集内容をjsonフォーマットでダウンロード

File > Download JSON をクリック

編集

編集中の定義をjsonからyamlに変換する

Edit > Convert to YAML をクリック

編集中の定義をクリアする

Edit > Clear editor をクリック

Git Branchの管理

ブランチの追加

Branch > Add Branch をクリック
From GitObject を選択
Add Branch Name を入力
Create ボタンをクリック

ブランチのリネーム

Branch > Rename Branch をクリック
From Branch を選択
To Branch Name を入力
Rename ボタンをクリック

ブランチの削除

Branch > Delete Branch をクリック
Branch を選択
Delete ボタンをクリック

ブランチの切り替え

Branch > Switch Branch をクリック
Branch を選択
Switch ボタンをクリック

ブランチ間マージ

Branc > Merge Branch をクリック
From Branch を選択
To Branch を選択
Merge ボタンをクリック

Git Tagの管理

タグの追加

Tag > Add Tag をクリック
From GitObject を選択
Add Tag Name を入力
Create ボタンをクリック

タグのリネーム

Tag > Rename Tag をクリック
From Tag を選択
To Tag Name を入力
Rename ボタンをクリック

タグの削除

Tag > Delete Tag をクリック
Tag を選択
Delete ボタンをクリック

Git Commit Userの管理

Gitリモートリポジトリを利用しない場合、ユーザごとに異なるローカルリポジトリが作成されます。

コミットユーザの追加

User > Add User をクリック
id を入力
email を入力
Create ボタンをクリック

コミットユーザの削除

User > Delete User をクリック
User を選択
Delete ボタンをクリック

コミットユーザの切り替え

User > Switch User をクリック
User を選択
Change ボタンをクリック

コミットメッセージの変更

User > Commit Msg をクリック
message を入力
Save ボタンをクリック

Generate

Language（Generator）毎に対応しているオプションを指定できます。

Serverリソースの生成

generate server > 対象のLanguage（Generator）をクリック

popup.左ペイン.Option Definition をクリック
指定できるオプションを確認

popup.左ペイン.Option Value をクリック
オプションを設定

Generate ボタンをクリック

Clientリソースの生成

generate client > 対象のLanguage（Generator）をクリック

popup.左ペイン.Option Definition をクリック
指定できるオプションを確認
popup.左ペイン.Option Value をクリック
オプションを設定
Generate ボタンをクリック

4.1.3. Swagger UI

デフォルト設定の場合、 http://localhost:9700/ui でアクセスできます。

spec-mgrで管理しているOASの定義を表示する

headerのURLを http://localhost:9701/specs/${SPEC_ID} に変更
Explore ボタンをクリック

4.2. CLI

4.2.1. bin/generate

codegen-cli の呼び出しに、カスタムTemplate, カスタムLanguage（Generator）の考慮を加えた薄いwrapperです。 codegen-cli自体の利用方法は codegen-cliのマニュアルで確認してください。

Language（Generator）のオプションを確認する

TARGET_LANGUAGE="typescript-angular"

bin/generate \
  config-help \
  -l ${TARGET_LANGUAGE}

組み込みLanguage（Generator）でリソースを生成する

SPEC_ID="sample"
TARGET_LANGUAGE="typescript-angular"

bin/generate \
  generate \
  -i http://localhost:9701/specs/${SPEC_ID} \
  -l ${TARGET_LANGUAGE} \
  -o output/${TARGET_LANGUAGE}

# 結果確認
find output/${TARGET_LANGUAGE} -type f

組み込みLanguage（Generator） + カスタムTemplate でリソースを生成する

SPEC_ID="sample"
TARGET_LANGUAGE="typescript-angular"
CUSTOM_TEMPLATE="CustomTemplateName"

bin/generate \
  generate \
  -i http://localhost:9701/specs/${SPEC_ID} \
  -l ${TARGET_LANGUAGE} \
  -t config/templates/${CUSTOM_TEMPLATE} \
  -o output/${TARGET_LANGUAGE}

# 結果確認
find output/${TARGET_LANGUAGE} -type f

カスタムLanguage（Generator） Jar形式でリソースを生成する

SPEC_ID="sample"
TARGET_LANGUAGE="CustomLanguageName"

bin/generate \
  -cl ${TARGET_LANGUAGE} \
  -i http://localhost:9701/specs/${SPEC_ID} \
  -o output/${TARGET_LANGUAGE}

# 結果確認
find output/${TARGET_LANGUAGE} -type f

カスタムLanguage（Generator） Groovy形式でリソースを生成する

TARGET_LANGUAGE="CustomLanguageNameGroovy"

bin/generate \
  -cl ${TARGET_LANGUAGE} \
  -i http://localhost:9701/specs/${SPEC_ID} \
  -o output/${TARGET_LANGUAGE}

# 結果確認
find output/${TARGET_LANGUAGE} -type f

4.2.2. module/swagger-spec-mgr/bin/git/

User追加（clone/init）

# リポジトリ初期化処理
#   GIT_REMOTE_REPOSITORY_URL が定義されている場合、git clone
#   定義されていない場合、git init を実行します。
#
# 引数
#   1: コミットユーザ      ※任意
#   2: コミットユーザemail ※任意
#
# オプション
#   -f | --force: 強制初期化モード
#     Git作業ディレクトリが既に存在する場合、削除してから初期化します。
#
module/swagger-spec-mgr/bin/git/clone.sh

remoteリポジトリ設定

# remote origin設定処理
#
# 引数
#   1: リモートリポジトリURL
#   2: コミットユーザ ※任意
#
module/swagger-spec-mgr/bin/git/add_origin.sh REMOTE_URL

コミット操作

commit/pull

# リポジトリ更新取得処理
#   リモートリポジトリ が設定されている場合、カレントブランチで、git pull
#   定義されていない場合、スキップします。
#
# 引数
#   1: コミットユーザ ※任意
#
module/swagger-spec-mgr/bin/git/pull.sh

push

# リポジトリ更新反映処理
#   リモートリポジトリ が設定されている場合、git commit & push
#   定義されていない場合、git commit だけを実行します。
#
# 引数
#   1: コミットコメント
#   2: コミットユーザ   ※任意
#
module/swagger-spec-mgr/bin/git/push.sh MESSAGE

ブランチ操作

ブランチ一覧

# ブランチ一覧取得処理
#
# 引数
#   1: コミットユーザ ※任意
#
module/swagger-spec-mgr/bin/git/branch_list.sh 2>/dev/null

ブランチ存在確認

# ブランチ存在確認処理
#
# 引数
#   1: 対象ブランチ名
#   2: コミットユーザ ※任意
#
module/swagger-spec-mgr/bin/git/branch_is_exist.sh BRANCH 2>/dev/null

カレントブランチ確認

# 現在ブランチ存在確認処理
#
# 引数
#   1: コミットユーザ ※任意
#
module/swagger-spec-mgr/bin/git/branch_get_current.sh 2>/dev/null

ブランチ切り替え

# ブランチ切り替え処理
#
# 引数
#   1: 切り替え先ブランチ
#   2: コミットユーザ ※任意
#
module/swagger-spec-mgr/bin/git/switch.sh BRANCH

ブランチ追加

# ブランチ追加処理
#
# 引数
#   1: 作成元（ブランチ or タグ or コミットハッシュ）
#   2: 対象ブランチ名
#   3: コミットユーザ ※任意
#
module/swagger-spec-mgr/bin/git/branch_add.sh FROM TO

ブランチリネーム

# ブランチリネーム処理
#
# 引数
#   1: リネーム元ブランチ名
#   2: リネーム先ブランチ名
#   3: コミットユーザ ※任意
#
module/swagger-spec-mgr/bin/git/branch_rename.sh FROM TO

ブランチ削除

# ブランチ削除処理
#
# 引数
#   1: 対象ブランチ名
#   2: コミットユーザ ※任意
#
module/swagger-spec-mgr/bin/git/branch_remove.sh BRANCH

ブランチマージ

# ブランチ間マージ処理
#
# 引数
#   1: マージ元ブランチ名
#   2: マージ先ブランチ名
#   3: コミットユーザ ※任意
#
module/swagger-spec-mgr/bin/git/branch_merge.sh FROM TO

タグ操作

タグ一覧

# タグ一覧取得処理
#
# 引数
#   1: コミットユーザ ※任意
#
module/swagger-spec-mgr/bin/git/tag_list.sh 2>/dev/null

タグ存在確認

# タグ存在確認処理
#
# 引数
#   1: 対象タグ名
#   2: コミットユーザ ※任意
#
module/swagger-spec-mgr/bin/git/tag_is_exist.sh TAG 2>/dev/null

タグ追加

# タグ追加処理
#
# 引数
#   1: 作成元（ブランチ or タグ or コミットハッシュ）
#   2: 対象タグ名
#   3: タグメッセージ
#   4: コミットユーザ ※任意
#
module/swagger-spec-mgr/bin/git/tag_add.sh FROM TO MESSAGE

タグリネーム

# タグリネーム処理
#
# 引数
#   1: リネーム元タグ名
#   2: リネーム先タグ名
#   3: コミットユーザ ※任意
#
module/swagger-spec-mgr/bin/git/tag_rename.sh FROM TO

タグ削除

# タグ削除処理
#
# 引数
#   1: 対象タグ名
#   2: コミットユーザ ※任意
#
module/swagger-spec-mgr/bin/git/tag_remove.sh TAG

4.3. Generate Specification

swagger-core で、ソースからOASを生成できます。

各言語への拡張などは https://swagger.io/open-source-integrations/ で紹介されています。利用するツールの利用方法に従ってください。

4.4. Customize

4.4.1. Custom Template

Template実装

mkdir config/templates/yourCustomTemplateName
cp -p config/templates/_default/JavaSpring/* config/generators/yourCustomTemplateName/

参考リンク
- https://qiita.com/Quramy/items/c583f3213f0b77ff1bac

4.4.2. Custom Generator

Java

swagger-codegenで提供されているカスタマイズ方法です。 buildしたjarを config/generators 配下のディレクトリに配置すると bin/generate、swagger-editorのgenerate機能で利用できます。

スキャフォルドの生成

bin/generate meta \
  -o path/to/yourCustomGeneratorWorkspace \
  -n yourCustomGeneratorName \
  -p com.domain.your

Generator, Templateの実装
- https://github.com/swagger-api/swagger-codegen#making-your-own-codegen-modules
- https://github.com/swagger-api/swagger-codegen/wiki/How-to-add-a-generator-for-a-new-language-or-framework
ビルド

cd path/to/yourCustomGeneratorWorkspace/
mvn package

配置

cd ${IN-HOUSE-SWAGGER_HOME}
mkdir config/generators/yourCustomGeneratorName
mv path/to/yourCustomGeneratorWorkspace/target/yourCustomGeneratorName_*.jar config/generators/yourCustomGeneratorName/

serverの再起動 ※Editorから利用する場合

bin/server restart

Groovy

Groovy実装

mkdir -p config/generators/yourCustomGeneratorName/generator
touch config/generators/yourCustomGeneratorName/generator/yourCustomGeneratorName.groovy

Template実装

mkdir config/generators/yourCustomGeneratorName/template
cp -p config/templates/_default/JavaSpring/* config/generators/yourCustomGeneratorName/template/

参考リンク
- https://qiita.com/Quramy/items/c583f3213f0b77ff1bac

in-house-swagger 0.5.2

1. Overview

1.1. Feature

1.2. Workflow

1.3. Architecture

1.4. Licenses

2. Installation

2.1. Target OS

2.2. Dependencies

2.3. Getting Started

3. Configuration

3.1. config/

3.1.1. project.properties

3.2. module/swagger-spec-mgr/config/

3.2.1. swagger-spec-mgr.properties

3.2.2. application.yml

4. Manual

4.1. Web

4.1.1. Server Control

起動

停止

再起動

4.1.2. Swagger Editor

Specの管理

開く

新規保存

上書き保存

削除

URLを編集画面にimport

ローカルファイルを編集画面にimport

編集内容をyamlフォーマットでダウンロード

編集内容をjsonフォーマットでダウンロード

編集

編集中の定義をjsonからyamlに変換する

編集中の定義をクリアする

Git Branchの管理

ブランチの追加

ブランチのリネーム

ブランチの削除

ブランチの切り替え

ブランチ間マージ

Git Tagの管理

タグの追加

タグのリネーム

タグの削除

Git Commit Userの管理

コミットユーザの追加

コミットユーザの削除

コミットユーザの切り替え

コミットメッセージの変更

Generate

Serverリソースの生成

Clientリソースの生成

4.1.3. Swagger UI

spec-mgrで管理しているOASの定義を表示する

4.2. CLI

4.2.1. bin/generate

Language（Generator）のオプションを確認する

組み込みLanguage（Generator）でリソースを生成する

組み込みLanguage（Generator） + カスタムTemplate でリソースを生成する

カスタムLanguage（Generator） Jar形式 でリソースを生成する

カスタムLanguage（Generator） Groovy形式 でリソースを生成する

4.2.2. module/swagger-spec-mgr/bin/git/

User追加（clone/init）

remoteリポジトリ設定

コミット操作

commit/pull

push

ブランチ操作

ブランチ一覧

ブランチ存在確認

カレントブランチ確認

ブランチ切り替え

ブランチ追加

ブランチリネーム

ブランチ削除

ブランチマージ

タグ操作

タグ一覧

タグ存在確認

カスタムLanguage（Generator） Jar形式でリソースを生成する

カスタムLanguage（Generator） Groovy形式でリソースを生成する