https://blog.csdn.net/itguangit/article/details/78978296
闊歩使用
由于不喜欢csdn的markwoen编辑器,对代码样式支持不好,看着不舒服,对审美要求比较高的同学移步github:https://github.com/itguang/swagger/tree/master/springboot-swagger-demo1
不知道怎么调整csdn的代码样式,有高人知道,请私信我一下.
闊歩使用は何ですか?
闊歩はベースの「オープンAPI宣言」(OpenAPIの仕様、OAS)、するために、人気の高いAPI開発フレームワークである
、APIは、適切な解決策は非常に大規模なプロジェクトで提供を通じて、開発サイクルに(デザインを含みますコーディングとテスト、ほとんどすべての言語がサポートされています)。
闊歩は生成、説明、RESTfulなWebサービスのための可視化・コールのための標準化と完全なフレームワークです。
全体的な目的は同じレートのアップデートでサーバーとして、クライアントとファイルシステムを作成することです。
メソッド、パラメータやモデルがしっかりAPIが常に同期することができ、ファイルサーバー側のコードに統合されています。闊歩は、経営陣が展開し、強力なAPIは、かつてないほど容易になりました使用することができます。
一般的な原則をspringfox:
一般的な原理springfoxは、種、初期化処理におけるスプリング・コンテキスト、上プロジェクトの開始である
現在のコンテキストにいくつかの闊歩関連Beanをロードするように構成されたデータを使用して自動的にフレームワーク、および自動システムは、これらのクラスのAPIドキュメントを生成する必要があるかもしれないスキャン、
対応するキャッシュされた情報を生成します。プロジェクトMVC制御層である場合、自動的にすべてのspringMvc Controllerクラスをスキャンし、文書に対応する記述データを生成します。
JSONデータ・パスを介してフォーマット:データへLOCATION / V2 / API-ドキュメントへのアクセス、および対応するドキュメントを生成するが、このデータに基づいてswaggerUIインタフェースを記述する。
我々は、このデータを取得することができますので、私たちは、あなた自身のページを生成することができます。
SpringBootとSwagger2を
強力な注釈するためにJavaを備え、我々は。使用することは非常にシンプルで、Swagger2を組み合わせることSpringBootを使う
ための人気の春の、マーティ・ピットは、過去に闊歩するspringmvcへの統合のために、Springベースのコンポーネント威張っ-springmvcを書きました。
最初のステップ:新しいSpringBootプロジェクト、依存関係の導入。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
1
2
3
4
5
6
7
8
9
10
11
12
上記の2つの効果がに依存しています:
springfox-swagger2はまだJSONファイルのAPIの説明ですが、このコンポーネントの機能は自動的にJSONファイルを生成するために私たちを支援することです、依存OSAの仕様書であり、
よりに、springfox-闊歩-UIはJSONファイルを解析することです優しい方法それが発表しました。
ステップ2:APIを作成します。
/ **
- @author itguang
@Create 2018年1月5日午前8時23分
** /
@RestController
パブリッククラスUserControllerで{@RequestMapping( "/こんにちは"、メソッド= RequestMethod.GET)
パブリック文字列のHello(){
戻り"ハロー"。
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
設定Swagger2
我々はそれを構成する必要はありませんので、今Swagger2は、私たちのためにAPIドキュメントを生成しません。
次のように我々は、コンフィギュレーション・クラスを作成する必要があります。
/ **
- @author itguang
@Create 2018年1月4日午前13時36
** /
@Configuration
@ EnableSwagger2
パブリッククラスSwaggerConfig {@Bean
公衆整理createRestApi(){
新しい整理を返す(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
(RequestHandlerSelectors.basePackage( "com.itguang.springbootswaggerdemo1.web")).apis
.paths(PathSelectors。任意の())
.build();
}プライベートApiInfo apiInfo(){
新しいApiInfoBuilderを返す()
.TITLE( "春ブーツ中使用Swagger2构建RESTfulなAPI")
.DESCRIPTION( "API文档构建利器休む")を
.termsOfServiceUrl(「http://blog.csdn.net/ itguangit ")
が.contact(" itguang ")
.version(" 1.0" )
.build();
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
springfoxがドケット(意味の要約)クラスを提供してくれ、私たちは豆は、春に注入され、それを確認する必要があり
、我々は設定ファイルを必要とし、方法(明らかにそれはコメントになります)によって、明らかにプログラムに指示しますこれは闊歩プロファイルです。
springfoxは(もちろん、このクラスを構築することができず、ヌルを直接使用するが、このAPIのあなたは、Aが低すぎる)私たちはドケットにコンストラクタのパラメータとしてApiInfoクラスに情報を組み合わせることができます。
得ます
今、私たちは、設定を行う必要があるが訪れ、私たちはこのプロジェクトを始めましょう、生成されたAPIドキュメントの基本的な要件を満たすことができましたします。http://localhost/swagger-ui.html
あなたは、次のインタフェースが表示されます。
これが私たちのために生成され威張っ-UIインターフェイスです。
Swagger2は、注釈を使用します
次に、我々は慎重に私たちが提供するのにspringfox-swagger2下の注意事項を検討します。
私たちは、コントローラを作成、Userクラスは、一般的なCRUD操作を実行するために使用されます
/ **
- @author itguang
- @Create 2018年1月4日13時31
** /
@RestController
@RequestMapping(値= "/ユーザ"、= APPLICATION_JSON_VALUEを生成します)//戻り値設定ファイルアプリケーション/ JSON
@Api(説明= "ユーザ管理")
のパブリッククラスHelloController {中
ArrayList<User> users = new ArrayList<>();
@ApiOperation(value = "获取用户列表", notes = "获取所有用户信息")
@RequestMapping(value = {""}, method = RequestMethod.GET)
public List<User> hello() {
users.add(new User("逻辑", "luoji"));
users.add(new User("叶文杰", "yewenjie"));
return users;
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
あなたは、我々はノートを(「すべてのユーザー情報を取得します」=指摘し、値=「ユーザーの一覧を取得」)@Api(説明=「ユーザ管理」)はアプローチで@ApiOperationを使用して、コントローラ上の注意事項使用することを見ることができます
?どのような影響これは、それが再び次の訪問私たちはああを試すことができ調達する必要があります。
私たちは、赤いボックスが変更された場所に入れることができ、そして我々が自動的に戻り値の型を決定するのは驚くべきことです:
[
{
"年齢":0、
"電子メール": "文字列"、
"有効":真、
"ID": "文字列"、
"パスワード": "文字列"、
"ユーザ名": "文字列"
}]
1
2
3
4
5
6
7
8
9
10
?しかし、我々は選択フィールドを無視したい場合は、ではなくUserクラス内のすべてのフィールドは、外出先で公開される心配しないでください、私たちは別の注釈を使用することができます@ApiModelProperty(=真の隠された)を
この注釈は、フィールドやメソッドは、APIドキュメントを生成されない限り、隠し属性が真であるとして、フィールドやメソッドに適用することができます。
次のように:
/ **
- @author itguang
@Create 2017年12月30日14時39分
** /
@Data
パブリッククラスユーザー{プライベート文字列ID;
プライベート文字列のユーザ名。
@ApiModelProperty(=真の隠された)
プライベート文字列のパスワード。プライベート文字列電子メール;
プライベート整数歳。
プライベートブールが有効。
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
我々が意図的にパスワードフィールドを無視し、再びブラウザをリフレッシュし、あなたが表示されます。
実際、パスワードフィールドがなくなっています。
次はシミュレートされたユーザーのAPIを作成しました:
@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
@RequestMapping(value = "/create", method = RequestMethod.POST)
public User postUser(User user) {
return user;
}
1
2
3
4
5
6
我々は、ユーザーのUserオブジェクトを作成するためのクライアントを渡す必要があり、ここで私たちは何もしない、ただユーザーオブジェクトが正常に作成表現するために、クライアントに返さ受けていることがわかります。
私たちは、ブラウザを更新するために見て:
私たちは、ああ、非常に満足していますので、ユーザーを作成するときに、ああ、我々は必要としない、または我々は解決策を持って、心配しないで最初のいくつかのフィールド、最初の何のフィールドの説明、リクエストパラメータを見ることはできません。
@ApiModelProperty(=真の隠された)
プライベート文字列ID;
@ApiModelProperty(value = "用户名")
private String username;
@ApiModelProperty(value = "密码")
private String password;
@ApiModelProperty(value = "邮箱")
private String email;
@ApiModelProperty(hidden = true)
private Integer age;
@ApiModelProperty(hidden = true)
private Boolean enabled;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
私たちは、上記のコメントの分野でのユーザーオブジェクトを追加します。@ApiModelProperty(=真の隠された)と@ApiModelProperty(値は=「ユーザ名」)
value属性は、フィールドの意味(説明説明)を指定し、再度実行してくださいするには、ブラウザを更新します。
どのように、それは非常に簡単ではありません。
ここでは、パラメータを渡す方法を見て:ユーザIDに基づいて情報を取得するメソッドを追加します
@ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
@RequestMapping(value = "getUser/{id}", method = RequestMethod.GET)
public User getUser(
@PathVariable(value = "id") String id) {
return new User(id, "itguang", "123456");
}
1
2
3
4
5
6
7
8
参照するには、ブラウザを更新
私たちは、今、私たちは、このパラメータに我々が行うことになったり、それはこのような単純なことができ、心配しないで記述(説明)、与える、クライアントのパラメータIDを渡すためにIDが必要?:
@ApiOperation(値= "ユーザのIDのURLを取得するなどの詳細"ノートを= "ユーザーの詳細を取得")
@RequestMapping(値= "のgetUser / {ID}"、= RequestMethod.GET方法)
public User getUser(@ApiParam(value = "用户id", required = true) //[注意] @ApiParam与 Controller中方法并列使用,也可以省略的
@PathVariable(value = "id") String id) {
return new User(id, "itguang", "123456");
}
1
2
3
4
5
6
7
8
私たちは、この注釈方法の上記パラメータは、上記の方法で直接使用することができないことに注意し、@ApiParam(=真に必要な値は=「ユーザID」を、)この注釈を追加しました。
もう一度お使いのブラウザを更新します:
一般的な注釈:
上記の理解を通じて、我々はおそらくSwagger2を使用する必要がありますが、我々は唯一のシステム要約してみましょう、いくつかの簡単な一般的な注意事項を紹介:
Swagger2基本的な使用(太字強調して):
@Api: 描述类/接口的主要用途
@ApiOperation: 描述方法用途
@ApiImplicitParam: 描述方法的参数
@ApiImplicitParams: 描述方法的参数(Multi-Params)
可以在上面 创建用户的方法上添加 @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")试试看.
@ApiParam:请求属性
@ApiIgnore: 忽略某类/方法/参数的文档
注意与 @ApiModelProperty(hidden = true)不同, @ApiIgnore 不能用在模型数据上
@ApiResponse:响应配置
如: @ApiResponse(code = 400, message = "无效的用户信息") ,注意这只是在 生成的Swagger文档上有效,不要和实际的客户端调用搞混了.
通常我们都是统一JSON返回,用不到这个注解
@ApiResponses:响应集配置
@ResponseHeader: 响应头设置
例如: @ResponseHeader(name=”head1”,description=”response head conf”)
@ApiModelProperty:添加和操作模型属性的数据
私は中国を見てみたいです
上記の導入後、あなたはSwagger2を使用する必要がありますが、一部の人々のために、受け入れることは非常に難しい英語表現上記参照、何の中国人はありませんか?
そこ!
公式文書の指示に従って、そしてspringbootのインターフェイス言語を置き換える我々はSpringBootリソースディレクトリの理解を持っている必要があり、すべての最初の、非常に簡単です:
春ブートデフォルトの「合意」これらのサブディレクトリのリソースディレクトリから静的リソースを読みます
src/main/resources/META-INF/resources
src/main/resources/static (推荐)
src/main/resources/public
1
2
3
栗の場合:画像はkumamon.jpgは、静的なディレクトリの下にあります
アクセスアドレスます。http:// localhost:8080 / IMG / kumamon.jpg
注意:ディレクトリが同じパス異なる静止画が含まれている場合は、優先順位を押し、最高のMETA-INF / resourcesディレクトリの優先順位。
リソースディレクトリの優先順位を理解SpringBoot、オープンのmavenはそれを見つける依存の前に導入さspringfox-闊歩-uiパッケージを見てみましょう:
次のように展開します。
なぜ私たちは、ブラウザの入力のhttp前に覚えています://localhost/swagger-ui.htmlページあなた闊歩が表示されます、はい、それは、ここにあります
ホームは、どこ闊歩-ui.htmlです
OPEN LOOK:
<!DOCTYPE HTML>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
私は読むことができない?まあ、それは問題ではありません理解していない、我々は我々が行うことになって、完成をしたいですか?
私たちは、直接私たちが先にそれに述べたリソースの優先春bootディレクトリを覚えて、ああ、ここにソースコードを変更することはできません?はい、私たちは覚えているラインああ上のプロジェクト内のリソースのMETA-INFディレクトリを作成する必要があり、
春のブート時のデフォルトになる私たちのプロジェクトのsrc /メイン/リソース/メタ- INF /リソース他のファイルの依存関係の下でカバー。
話し始め
次のように、リソースディレクトリのsrc /メイン/リソース/ META-INF /リソースを作成します。
次のように闊歩-ui.htmlを読み取ります。
<!DOCTYPE HTML>
<script src='webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/lodash.min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/backbone-min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/swagger-ui.min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/jsoneditor.min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/marked.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/swagger-oauth.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/springfox.js' type='text/javascript'></script>
<!--国际化操作:选择中文版 -->
<script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
実際には、我々は唯一の2行のコードを追加します。
1
2
3
以下のようZH-cn.js文書が読み取ります。
「厳格な使用」;
/ * Jshintのquotmark:ダブル* /
window.SwaggerTranslator.learn({
「警告:非推奨の」:「警告:廃止」、
「実装メモ」:「備考を実現する」、
「レスポンス・クラス」:「応答タイプ」、
「ステータス「:」状態「
『パラメータ『:』パラメータ』、
『パラメータ『:』パラメータ』、
『値『:』値』、
『説明『:』説明』、
『パラメータタイプ『:』パラメータタイプ』、
」データ型「:」データタイプ「
『メッセージ応答『:』応答メッセージ』、
『HTTPステータスコード『:』HTTPステータスコード』、
『理由『』理由』、
『モデル応答『:』応答モデル』、
」リクエストURL「:」URLを要求した「
『リクエストヘッダ『:』リクエストヘッダ』、
『レスポンスボディ『:』身体に応じて』、
『応答コード『:』応答コード』、
『レスポンスヘッダ『:』レスポンスヘッダ』、
」応答を非表示「:」隠されたレスポンス」、
『ヘッダ『:』頭』
「それを試してみてください!」:「お試しください!」、
「表示/非表示」:「表示/非表示」、
「操作のリスト」:「表示動作」、
「事業を拡大」:「操作を展開し、」
「生の」: "オリジナルの
「」はできません解析JSON生の結果『:』 JSONオリジナル結果を解析することができません「、
『例の値『:』例』、
『パラメータ値として設定するにはクリックして『:』セットのパラメータをクリックして』、
」モデルのスキーマ「:」モデルのアーキテクチャ」、
『モデル『:』モデル』、
『適用『:』アプリケーション』、
『ユーザ名『:』ユーザー名』、
『パスワード『:』パスワード』、
『サービスの条件『:』サービスの条件』 、
「作成者」:「によって作成されました」
"で詳細を参照してください「:」もっと見る:「
『開発者向けのビジネスカード『:』連絡先の開発』、
『APIバージョン『:』APIバージョン』、
『レスポンスコンテンツタイプ『:』タイプの応答内容』、
タイプの」パラメータの内容:「:」パラメータの種類:「
」フェッチ資源「:」取得リソース」
「フェッチリソースリスト」:「リソース・リストの取得」、
「エクスプローラ」:「ブラウズ」、
「ショー闊歩Petstoreの例アピス」:「闊歩Petstoreのは、アピスの一例を示した」
缶のそれはでていていない可能性があります読んでからサーバー」ではありません。適切なアクセス制御用の原点の設定。 「:」 サーバーから読み取ることができない「...アクセス制御用の原点正しく設定されないことがあり
、 『してくださいプロトコルで指定するための『:』の合意を指定してください:』、
」することができないの読み取り闊歩をJSON「:」で闊歩JSONを読み取ることができません」、
『UIをレンダリング完成リソース情報ロード闊歩。『:』UI闊歩をレンダリングしているロードされたリソース情報』、。
『読み取りAPIにできない『:』』 APIを読み取ることができません、
「パスから」:「パスから」、
「サーバが返さ」:「サーバ戻ります」
})。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
また、それはあなた自身の中国の名前を定義することができます。
GETを話します。
これは、闊歩のは非常に簡単ではありません、作業が行われている終え、HTTPを訪問し、プロジェクトを再起動します。あなたはドキュメントが完全に終了していることがわかります//localhost/swagger-ui.html。
要約:
さて、ここでのプロジェクトでSwagger2チュートリアルに。
ソースのダウンロード:https://github.com/itguang/swagger/tree/master/springboot-swagger-demo1
著者:PostTruth
出典:CSDN
オリジナルます。https://blog.csdn.net/itguangit/article/details/78978296
著作権:この記事はブロガーオリジナル記事ですが、再現し、ボーエンのリンクを添付してください!