説明:、言語に依存しない、この表現だけでなく、シンプルで強力なAPI表現標準で闊歩残りは人間が読めると機械可読。インタラクティブドキュメントは、クライアントとサーバーのコードを生成するインターフェース形式休憩APIとして記述することができるよう、残りのAPIを使用することができます。
より一般的なシナリオに関連して以下に、おそらく良いドッキングインターフェースを行うには、フロントとバックエンド開発者のためのインターフェイスを管理するためにSpringbootで闊歩を使用する方法を次を参照するだけでなく、フォローアップ保守インタフェースの発展に資します。
1.のpom.xmlの依存関係が導入さ闊歩が必要:
1 <! - Swagger2コア依存- > 2 < 依存性> 3 < のgroupId > io.springfox </ のgroupId > 4 < たartifactId > springfox-swagger2 </ たartifactId > 5 </ 依存> 6。 <! -闊歩-UI APIは、ディスプレイ及びインタフェーステストプロジェクトを提供する- > 7 < 依存性> 。8 < のgroupId > io.springfox </ のgroupId > 9 < たartifactId >springfox-闊歩-UI </たartifactId > 10 </ 依存> 11
2.管理し、維持するために、通常クラスで、いくつかの静的リソース構成ファイルの闊歩を指定します
Swagger2Configuration.class
1 インポート org.springframework.context.annotation.Bean。 2 インポート org.springframework.context.annotation.Configuration。 3 輸入 springfox.documentation.builders.ApiInfoBuilder。 4 インポート springfox.documentation.builders.PathSelectors。 5 輸入 springfox.documentation.builders.RequestHandlerSelectors。 6 インポート springfox.documentation.service.ApiInfo。 7 インポート springfox.documentation.spi.DocumentationType。 8 インポート springfox.documentation.spring.web.plugins.Docket。 9 インポートspringfox.documentation.swagger2.annotations.EnableSwagger2; 10 11 12 @Configuration 13 EnableSwagger2 @ 14 パブリック クラス Swagger2Configuration { 15 @Bean 16 公衆整理createRestApi(){ 17 リターン 新しいドケット(DocumentationType.SWAGGER_2) 18 .apiInfo(apiInfo()) 19 .select() 20 .apis(RequestHandlerSelectors .basePackage( " com.xuecheng ")) 21 .paths(PathSelectors.any()) 22 .build(); 23である } 24 25 プライベート ApiInfo apiInfo(){ 26が 戻り 、新しい新しい ApiInfoBuilder() 27 .TITLE(「ファイルのアップロードおよびデモをダウンロード ") 28 (" .DESCRIPTION ファイルのアップロードとデモをダウンロードする ") 29 // .termsOfServiceUrl(" / ") 30 .version(" 1.0「) 31である .build(); 32 } 33は 34です }
3.どのように使用するには?
このステップでは、私は、インターフェイスを記述するために、より一般的なビジネスシナリオを使用します。
実際には、注釈付きコンテンツの大多数を避けるために、コントローラを可能にするために別のAPIインターフェイスを構築することにより、それを達成するためには、コントローラがあまりにも乱雑に見えたことができます
この層コントローラに直接そのような注釈(複数可)
1 @Api(値= " SWAGGERインタフェース ") 2 @RestController 。3 @RequestMapping(値=" / API /闊歩/ユーザ ") 。4 パブリック クラス SwaggerController { 5 @ApiOperation(値=" ユーザの詳細を取得 "、ノート= " 詳細パラメータに従ってユーザーを取得する ") 。6 @ApiImplicitParams({ 7 @ApiImplicitParam(名前は=" ID "値=" ユーザID "データ型が=" ロング "paramTypeは=" クエリ「) 。8 @ApiImplicitParam(名= "名前「値=」用户名字 "必要= 真、dataTypeと= " 文字列 "、paramType = " クエリ ")、 9 @ApiImplicitParam(名前=" 年齢 "、値= " 用户年龄 "、DataTypeが" ロング "、paramTypeは=" クエリ「) 10 }) 11 (値= ""、方法= RequestMethod.GET)@RequestMapping 12 @PostMapping( " / find1 ") 13 パブリック ユーザ検索(@ModelAttributeユーザのユーザ){ // @ ModelAttributeユーザーユーザ等效于ロングID、文字列名;ロング年齢; 14 戻る 新しい)(ユーザー; 15 } 16 }
以下のようにUserクラスであることを特徴とします。
1 // @ ApiModel(値= "ユーザ"、説明= "用户对象") 2つの パブリック クラスユーザー{ 3 @ApiModelProperty(値= " 用户ID " =必須真) 4 プライベートロングID。 5 @ApiModelProperty(=隠された真) 6 プライベート文字列名; 7 @ApiModelProperty(値= " 用户年龄 ") 8 プライベートロング歳。 9 公共 ボイド SETID(ロングID){ 10 この .ID = ID。 11 } 12 公衆 ボイドのsetName(文字列名){ 13 この .nameの=名前。 14 } 15 公共 ボイド setAge(ロング年齢){ 16 この .age =年齢。 17 } 18 公衆ロングのgetId(){ 19 リターン ID。 20 } 21 パブリック文字列のgetName(){ 22 リターン名。 23 } 24 公衆ロングgetAge(){ 25 リターン年齢。 26 } 27 28 } 29 30
Userクラスは〜クエリまたは各フィールドの意味を記述するために@ApiModelProperty属性を必要とするそれぞれのクエリ結果に対応するエンティティであり、ユーザー・クラスの@ApiModel注釈を選択的に与えることができます。
アクセス闊歩インターフェイスの説明ページ単にHTTPを入力し、プロジェクト(ここではspringboot)を起動:// localhostを:アクセスへ8080 /威張っ-ui.html#を、私たちは、対応するコントローラとのインタフェースをクリックして、あなたが見ることができます!:
偶然に領域が入力パラメータを記述し、出力応答を説明され、レスポンスがモデルに切り替えることが、あなたは、出力のフィールドの意味を確認できます。
:2)リクエストパラメータが複雑であり、この時間のような、エンティティ・クラスに対応しなければなりません
1 //@ApiModel(value="Params", description="传入参数") 2 public class Params { 3 @ApiModelProperty(name="param1", value = "参数1", required = true) 4 private String param1; 5 6 @ApiModelProperty(name="input", value = "输入", required = true) 7 private List<Input> input; 8 9 public String getParam1() { 10 return param1; 11 } 12 13 public void setParam1(String param1) { 14 this.param1 = param1; 15 } 16 17 public List<Input> getInput() { 18 return input; 19 } 20 21 public void setInput(List<Input> input) { 22 this.input = input; 23 } 24 25 }
返回是一个集合类型:
1 @ApiOperation(value="获取用户信息集合", notes="根据输入类型来获取用户信息集合") 2 @PostMapping("/find2") 3 @ApiResponse(response = User.class, responseContainer="List", code = 200, message = "请求成功") 4 public List<User> find2(@ApiParam(value="传入参数类型", required=true) @RequestBody Params params) { 5 6 return new ArrayList<User>(); 7 }
可以看到,现在无论是对于接口里再复杂的输入和输出,都能比较清楚地看到每个属性(字段)的含义,以及可以在swagger的ui上直接用Try it out 按钮来测试接口的可用性。
swagger可以很好地帮助我们管理项目接口~,以及不同业务侧之间的接口对接工作。