優雅なapiインタフェースドキュメントの作成方法

前言
今日は前に書いたインタフェースをドキュメントに整理する必要があります.ボスはswaggerで意見を出しました.私は新大陸を発見したように興奮して、待ちきれずにそれを「占有」しました.Swaggerは簡単に手に入るので、十数分でできました.ちょうど前のどのように優雅なフォーマットインタフェースに続いて、ここでSpringBootがSwaggerを統合する簡単な過程を話しましょう.
Swaggerの紹介
毎回getの新しい技能を分かち合いたい时、やり方によって言えば、1つのブロックがこの技能の“前世今生”を绍介する必要がありますが、私は30分を超えない配置を完成するまで接触して、私に完璧な绍介をさせるのは少し虚しいと思います.http://swagger.io/ http://swagger.io/irc/これはリアルタイムチャットルームで、外国人と「how are you?fine thk you.and you?」とコミュニケーションしたばかりです.https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodelこれはいくつかの注釈のapi Swaggerは3つのモジュールがあります

Swagger Editor

Swagger UI

Swagger Codegen Swagger UIを使用しています.個人的には「Swagger関連の注釈を使用してサービスを開始すると、対応するページでAPIを表示してテストすることができます」と理解しています.まず、最終的なインタフェースの説明、パラメータのタイプ、戻り例のオンラインデバッグを見てみましょう.まだ何をためらっているのか、早くcheckouコードをチェックして、やってみましょう

統合
私は前のコードの書き込み(私のGitHubで閲覧したり、直接cloneをローカルにしてapi-normsブランチに切り替えたりすることができます)、ここではSpringbootを使ってSwagger泥棒JBを統合するのは簡単で、比較的SpringMVCは複雑です.ここはともかく(これからは話さないかもしれませんが、Springbootを使ってから、SpringMVCを捨て始めました)
maven依存
古いしきたりで配置する

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>${swagger.version}version>
dependency>
<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>${swagger.version}version>
dependency>

Swagger注記の追加
Applicationに直接@EnableSwagger2を追加して、バージョンに注意して、公式サイトの上のバージョンはまだ最新に更新していないで、最新のGithubの上で見て、配置したコード

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Created by wangxc on 2017/3/9.
 */
@SpringBootApplication
@EnableSwagger2
public class Application {

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

はい、次はインタフェースの注釈を説明します!Controllerレイヤでは、次のように構成します.

package com.quick.api;


import com.quick.po.Address;
import com.quick.utils.BaseResp;
import com.quick.utils.ResultStatus;
import io.swagger.annotations.*;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;
import java.util.List;

/**
 * Created with IDEA
 * User: vector
 * Data: 2017/4/12
 * Time: 8:41
 * Description:
 */
@RestController
@RequestMapping("/api")
@Api("springboot  swagger2") // Swagger UI   api     
public class WebController {

    @ApiOperation("      ") //        
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query",name="province",dataType="String",required=true,value=" ",defaultValue="   "),//        ，  ，    ，    ，  ，   (         )
            @ApiImplicitParam(paramType="query",name="area",dataType="String",required=true,value="  ",defaultValue="   "),
            @ApiImplicitParam(paramType="query",name="street",dataType="String",required=true,value="  ",defaultValue="   "),
            @ApiImplicitParam(paramType="query",name="num",dataType="String",required=true,value="   ",defaultValue="666")
    })
    @ApiResponses({
            @ApiResponse(code=400,message="       "), //          
            @ApiResponse(code=404,message="               ")
    })
    @RequestMapping(value = "/address",method = RequestMethod.POST)
    public BaseResp
 getAddressInfo(@RequestParam(value = "province")String province,
                                   @RequestParam(value = "area")String area,
                                   @RequestParam(value = "street")String street,
                                   @RequestParam(value = "num")String num){

        if(StringUtils.isEmpty(province)||StringUtils.isEmpty(area)||StringUtils.isEmpty(street)||StringUtils.isEmpty(num)){
            return new BaseResp(ResultStatus.error_invalid_argument);
        }
        Address address = new Address();
        address.setProvince(province);
        address.setArea(area);
        address.setStreet(street);
        address.setNum(num);
        return new BaseResp(ResultStatus.SUCCESS,address);

    }

    @ApiOperation("      ")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query",name="province",dataType="String",required=true,value=" ",defaultValue="   "),
            @ApiImplicitParam(paramType="query",name="area",dataType="String",required=true,value="  ",defaultValue="   "),
            @ApiImplicitParam(paramType="query",name="street",dataType="String",required=true,value="  ",defaultValue="   "),
            @ApiImplicitParam(paramType="query",name="num",dataType="String",required=true,value="   ",defaultValue="666")
    })
    @ApiResponses({
            @ApiResponse(code=400,message="       "),
            @ApiResponse(code=404,message="               ")
    })
    @RequestMapping(value = "/address/list",method = RequestMethod.POST)
    public BaseResp> getAddressList(@RequestParam(value = "province")String province,
                                             @RequestParam(value = "area")String area,
                                             @RequestParam(value = "street")String street,
                                             @RequestParam(value = "num")String num){

        if(StringUtils.isEmpty(province)||StringUtils.isEmpty(area)||StringUtils.isEmpty(street)||StringUtils.isEmpty(num)){
            return new BaseResp(ResultStatus.error_invalid_argument);
        }
        Address address = new Address();
        address.setProvince(province);
        address.setArea(area);
        address.setStreet(street);
        address.setNum(num);
        List
 lists = new ArrayList<>();
        lists.add(address);
        lists.add(address);
        lists.add(address);
        return new BaseResp(ResultStatus.SUCCESS,lists);

    }
}

私はただ元の基礎の上で下の注釈を追加しました
名前
説明する
@Api()
クラスをSwaggerリソースとしてマークします.
@ApiOperation()
特定のパスに対する動作または通常httpメソッドについて説明する.
@ApiImplicitParams
複数のApiImplicitParamオブジェクトリストのパッケージを許可します.
@ApiImplicitParam
api操作の単一パラメータを表します.
@ApiResponses
複数のApiResponseオブジェクトリストのパッケージを許可します.
@ApiResponse
操作の可能な応答を説明します.
もっとここを見て
このように簡単で、基本的で強力なAPIドキュメントが整理されました!
開始
SpringBootを正常に起動すると、コンソールから出力されていることがわかります.

2017-05-03 21:42:52,975  INFO ClassOrApiAnnotationResourceGrouping:100 - Group for method getAddressList was springboot  swagger2
2017-05-03 21:42:52,986  INFO ClassOrApiAnnotationResourceGrouping:100 - Group for method getAddressList was springboot  swagger2

Swaggerが正常に走り出したことを説明して、次にブラウザを開けて、あなたのリンクyourdomain/swagger-uiを入力します.私のはhttp://localhost:8080/swagger-ui.html
インタフェースを見て点々とすると、上の注釈の意味がさらに理解できると信じています.
後記
ここに展示されているのはSwaggerの最も基本的な機能だけで、もっと強力な機能が後で運用されたら、私は更新し続けます.今私はapiを見てSwaggerUI入力ファイルのテストを探しています.インタフェースがあるので、ファイルをアップロードする必要があります.私が終わったら、また共有しましょう.　　
私の個人ブログへようこそ