春のブート2.xの基本チュートリアル：Swagger2を使用することで、強力なAPIドキュメントを構築します

人気のアーキテクチャとマイクロアーキテクチャのサービスの前後端の分離で、我々はより多くのシーンを構築するために春ブーツRESTfulなAPIプロジェクトを使用しています。IOSの開発者、Androidの開発者は、Web開発者、さらには他のバックエンドサービス：通常、我々はRESTfulなAPIは異なる開発者や開発チームの数にサービスを提供する可能性があります。開発中に、通常は頻繁に通信コストを削減するために、伝統的なアプローチは、インターフェイスのすべての詳細を記録するためにRESTfulなAPIのドキュメントや他のチームを作成することです、しかし、このアプローチにはいくつかの問題があります。

• 多くのインターフェイス、および複合体の詳細は、それ自体で、これは下流の流行を不平、非常に困難なことである高品質の文書を作成するには、（HTTPリクエスト、HTTPヘッダ、HTTPリクエストのコンテンツなどのさまざまな種類を考慮する必要があります）。
• 時間が経つにつれて、絶えず変更インタフェースは、インタフェース文書を修正するために、すべての回で同期させなければならない、と、厳格な管理の仕組みが存在しない限り、二つの異なるコードを持つ文書がなく、メディアでは、そうでない場合は簡単に不整合が生じます。

上記この問題を解決するために、この記事は重い良きパートナーRESTfulなAPIのSwagger2をご紹介します、それは簡単に春ブーツに統合され、強い組織RESTfulなAPIドキュメントとSpring MVCのプログラムとすることができます。記述内容と実装コードに統合するには、そのメンテナンスのドキュメントので、コードを変更し、一つに統合され、私たちは簡単にコードのロジックを変更すると同時に、ドキュメントを変更することを可能にする一方でそれは、私たちが文書を作成した作業量を減らすことができます。またSwagger2のページには、それぞれのRESTfulなAPIをデバッグするための強力なテスト機能を提供します。以下に示すように、特定の結果：

以下では、具体的闊歩を統合することで春ブーツで実装私たち自身のスターターの使用を記載しています。プロジェクトのGithubの統合：https://github.com/SpringForAll/spring-boot-starter-swagger。あなたが使用することが容易に見つけた場合は、スターたちをサポートして歓迎！

準備

まず、我々はあなたがこのタイプのコンテンツを行っていない場合、我々はあなたがチュートリアルを読むことをお勧めします、達成するために春のRESTful APIプロジェクトの起動を必要とする：
春2.xのブートの基本チュートリアル：RESTfulなAPIのユニットテストは、建物建設を。あるいは、サンプルは、以下の倉庫ベースのチュートリアルとして直接使用することができるchapter2-1プロジェクト。

• Githubの：https://github.com/dyc87112/SpringBoot-Learning/tree/2.x
• Gitee：https://gitee.com/didispace/SpringBoot-Learning/tree/2.x

統合Swagger2

ここでは、私たちの倉庫上記chapter2-1の改修プロジェクトを統合します。

最初のステップ：依存威張っスプリング・ブート・スターターを追加します。

ではpom.xml、次のように、依存関係の追加：

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.0.RELEASE</version>
</dependency>

ステップ：メインクラスが追加@EnableSwagger2Doc注釈を、次のように

@EnableSwagger2Doc
@SpringBootApplication
public class Chapter22Application {

    public static void main(String[] args) {
        SpringApplication.run(Chapter22Application.class, args);
    }

}

第3のステップは：application.propertiesのような、ドキュメントに関連するコンテンツを設定します

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.4.0.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=didi
swagger.contact.url=http://blog.didispace.com
[email protected]
swagger.base-package=com.didispace
swagger.base-path=/**

パラメータは以下の意味の各：

• swagger.title：タイトル
• swagger.description：説明
• swagger.version：バージョン
• swagger.license：ライセンス
• swagger.licenseUrl：ライセンスURL
• swagger.termsOfServiceUrl：サービスURLの利用規約
• swagger.contact.name：メンテナンス男
• swagger.contact.url：メンテナのURL
• swagger.contact.email：メンテナのメール
• swagger.base-package：基本パッケージ闊歩スキャン、デフォルト：フルスキャン
• swagger.base-path：URLを定期的に対処する必要があり、デフォルト：/ **

その他の構成手順見える公式の説明：https://github.com/SpringForAll/spring-boot-starter-swagger

四ステップ：訪問、アプリケーションを起動します。http://localhost:8080/swagger-ui.htmlあなたは次のインターフェイスのドキュメントのページを見ることができます：

ドキュメントのコンテンツの追加

積分闊歩の完了後、http://localhost:8080/swagger-ui.htmlページが表示されることがあり、各インターフェースの説明は英語であり、名前またはコードが生成定義に従います。これらは、ユーザーフレンドリーなコンテンツではありませんので、我々は、ドキュメントの独自のリッチコンテンツにいくつかの命令を追加する必要があります。当社が、以下に示すように@Api、@ApiOperation注釈はを通じて、APIに命令を増やし@ApiImplicitParam、@ApiModel、@ApiModelProperty図に注釈パラメータが上昇します。

このような次の例のように：

@Api(tags = "用户管理")
@RestController
@RequestMapping(value = "/users")     // 通过这里配置使下面的映射都在/users下
public class UserController {

    // 创建线程安全的Map，模拟users信息的存储
    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<>());

    @GetMapping("/")
    @ApiOperation(value = "获取用户列表")
    public List<User> getUserList() {
        List<User> r = new ArrayList<>(users.values());
        return r;
    }

    @PostMapping("/")
    @ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
    public String postUser(@RequestBody User user) {
        users.put(user.getId(), user);
        return "success";
    }

    @GetMapping("/{id}")
    @ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
    public User getUser(@PathVariable Long id) {
        return users.get(id);
    }

    @PutMapping("/{id}")
    @ApiImplicitParam(paramType = "path", dataType = "Long", name = "id", value = "用户编号", required = true, example = "1")
    @ApiOperation(value = "更新用户详细信息", notes = "根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户", notes = "根据url的id来指定删除对象")
    public String deleteUser(@PathVariable Long id) {
        users.remove(id);
        return "success";
    }

}

@Data
@ApiModel(description="用户实体")
public class User {

    @ApiModelProperty("用户编号")
    private Long id;
    @ApiModelProperty("用户姓名")
    private String name;
    @ApiModelProperty("用户年龄")
    private Integer age;

}

上記のコードを追加した後、訪問、プログラム春のブートを開始します。http://localhost:8080/swagger-ui.html中国の文書は（参照することにより、注釈付き文書の要素との対応を示した）説明を次のと、あなたが見ることができます：

APIドキュメントおよびデバッグアクセス

ページ上の要求を考慮して、我々は、ユーザーの値入力ボックスを参照してください？インターフェイス機能の表示にはい、闊歩のほか、だけでなく、デバッグテスト機能を提供し、我々は上の画像の右側にあるモデルスキーマをクリックすることができます（黄色のエリア：それはユーザーのデータ構造を示す）、この時間は、バリューにユーザーオブジェクトが存在しますテンプレート、我々は唯一の下をクリックし、少し適切な変更を必要とする“Try it out！”呼び出すための要求を完了するために、ボタンを！

POSTリクエストは、いくつかのGETリクエストで正しい前にこの時点で、あなたは確認することができます。

文書を書かれたこれらのインタフェースの作品と比較すると、我々は、設定内容が非常に小さく、合理化され増加し、オリジナルの侵略のためのコードは、範囲内に立っています。そのため、RESTfulなAPIを構築するAPIのドキュメント管理に闊歩を追加しながら、それは良い選択です。

サンプルコード

この論文の完全な作品は、リポジトリの下に表示することができますchapter2-2ディレクトリ：

• Githubの：https://github.com/dyc87112/SpringBoot-Learning/tree/2.x
• Gitee：https://gitee.com/didispace/SpringBoot-Learning/tree/2.x

あなたはこの記事が良い、歓迎されていると思われる場合Starのサポート、あなたの懸念は、私が力を主張です！

排他的な学習資源を整理し、毎日呉服を押します、プログラムAPE DD：私は公共の数の関心を歓迎します。：あなたは私のトピックの内容に興味があるなら、あなたは私のブログに焦点を当てることができdidispace.com