swaggerインターフェイスのドキュメント
1.スワッガー入門
フロントとリアの分離
Vue + springboot一連のソリューション
バックエンドの時代:フロントエンドは静的ページのみを管理します; html ===>バックエンド。テンプレートエンジンjspejbバックエンドが主力です
フロントエンドとバックエンドの分離の時代:
- バックエンド:バックエンド制御層、サービス層、データアクセス層[バックエンドチーム]
- フロントエンド:フロントエンドコントロールレイヤー(双方向バインディング)、ビューレイヤー[フロントエンドチーム]
- バックエンドデータを偽造します、json。それはすでに存在し、バックエンドは必要なく、プロジェクト全体を実行できます。
- フロントエンドとバックエンドはどのように相互作用しますか?===> API json
- 比較的独立したフロントエンドとリアエンド、緩く結合
- フロントエンドとバックエンドは異なるサーバーに展開できます
フロントエンドとバックエンドの分離、問題
- フロントエンドとバックエンドの統合と共同デバッグ、フロントエンドとバックエンドの担当者はそれを行うことができず、「リアルタイムで交渉し、できるだけ早く解決する」ため、最終的には問題の集中的な発生につながります
解決:
-
スキーマ[計画の概要]を指定します。統合のリスクを減らすために、最新のAPIをリアルタイムで更新します。
-
初期:ワードプラン文書を作成します。
-
フロントとリアの分離:
- フロントエンドテストバックエンドインターフェイス:postman
- バックエンドはインターフェースを提供し、最新のニュースや変更をリアルタイムで更新する必要があります。
スワガーが生まれる
- 世界で最も人気のあるapiフレームワークとして知られています
- 安らかなapiドキュメントオンライン自動生成ツール=> apiドキュメントとapi定義が同期および更新されます
- 直接実行し、apiインターフェイスをオンラインでテストします
- 複数の言語をサポートするjava、php、py ...
公式サイト:https://swagger.io
プロジェクトでswaggerスプリングボックスを使用する
- swagger2
- ui
第二に、springbootはswaggerを統合します
頼る
-
関連する依存関係をインポートする
- springfox-swagger2
- springfox-swagger-ui
-
pom
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
helloworldインターフェースを書く
package cn.bitqian.swagger.controller;
import org.springframework.web.bind.annotation.*;
/**
* hello world
* @author echo lovely
* @date 2020/10/28 19:23
*/
@RestController
public class HelloController {
@RequestMapping(value = "/hello")
public String hello() {
return "hello";
}
}
swaggerの構成==>構成構成クラス
スワッガーを開き、Enablexxx
@Configuration
@EnableSwagger2 // 开启swagger2
public class SwaggerConfig {
}
テスト走行
http:// localhost:8080 / swagger-ui.html
3、スワッガーを構成します
転送担当者にインターフェースの機能を伝え、コントローラーのインターフェースについて説明します。インターフェイスのアクセス許可を設定することもできます。
package cn.bitqian.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
/**
* swagger配置类
* @author echo lovely
* @date 2020/10/28 19:35
*/
@Configuration
@EnableSwagger2 // 开启swagger2
public class SwaggerConfig {
// 文档的标题,和描述!作者的信息deng..
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo());
}
// api 信息 接口文档的头部信息描述
public ApiInfo appInfo() {
Contact contact = new Contact("bitqian", "http://example.com", "[email protected]");
return new ApiInfo("bitqian的swagger文档",
"用来描述此接口的功能,内容。",
"v1.0",
"http://example.cn", contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
スワッガー構成スキャンインターフェイス
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo()).
select().
// RequestHandlerSelectors 配置要扫描的接口的方式
// basePackage 指定要扫描的包
// any() 扫描全部
// none() 不扫描
// withClassAnnotation(Controller.class) 扫描类上的注解, 生效
// withMethodAnnotation(RequestMapping.class) 扫描方法上的注解, 生效
apis(RequestHandlerSelectors.basePackage("cn.bitqian.swagger.controller")).
// paths(PathSelectors.ant("/bitqian/**")) 扫描指定的接口
// PathSelectors.regex("")
paths(PathSelectors.ant("/hello/**"))
.build();
}
実稼働環境でのみスワッガーを開始するにはどうすればよいですか?
- 実稼働環境かどうかを判断する
- インジェクトイネーブル
@Bean
public Docket docket(Environment environment) {
// 获取当前环境 是生产环境 启动swagger
boolean isProFlag = environment.acceptsProfiles(Profiles.of("pro"));
System.out.println("is dev environment....===========>" + isProFlag);
return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo()).groupName("bitqian").
enable(isProFlag). // 是否启动swagger 如果为false,则不能在浏览器中使用swagger
select().
apis(RequestHandlerSelectors.basePackage("cn.bitqian.swagger.controller")).
// paths(PathSelectors.ant("/hello/**")).
build();
}
apiドキュメントのグループ化を構成する
- 複数のドックを作成し、複数の人が異なるインターフェイスを作成します
@Bean
public Docket docket1() {
return new Docket(DocumentationType.SWAGGER_2).groupName("bitqian666 group1");
}
@Bean
public Docket docket12() {
return new Docket(DocumentationType.SWAGGER_2).groupName("bitqian666 group2");
}
第4に、スワッガー注釈はエンティティクラスとインターフェイスを説明するために使用されます
歌う
package cn.bitqian.swagger.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* 给实体类生成文档
* @author echo lovely
* @date 2020/10/29 21:09
*/
@ApiModel("user实体类")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
public User() {
}
public User(String username, String password) {
this.username = username;
this.password = password;
}
}
コントローラ
package cn.bitqian.swagger.controller;
import cn.bitqian.swagger.entity.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
/**
* hello world
* @author echo lovely
* @date 2020/10/28 19:23
*/
@RestController
public class HelloController {
@ApiOperation("get/post都可的hello接口")
@RequestMapping(value = "/hello")
public String hello() {
return "hello";
}
@ApiOperation("get的hello接口, 返回一个空 user")
@GetMapping(value = "/hello1")
public User hello1() {
return new User();
}
@ApiOperation("hello1 接口post way~")
@PostMapping(value = "/hello1")
public User hello1(@ApiParam("传递用户") User user) {
return user;
}
@ApiOperation("登录接口 post way~")
@PostMapping(value = "/login")
public String login(@ApiParam("登录用户名") @RequestParam("username") String username,
@ApiParam("登录密码") @RequestParam("password") String password) {
return "ok" + "{" + username + ", " + password + "}";
}
}
第五に、swaggerはインターフェースの説明情報しか提供できないと思いますか?え〜
スワガーはそれをテストすることができます
やってみて
六、ついに
- スワッガーを使用して、理解しにくい属性やインターフェースに注釈情報を追加できます。
- インターフェイスドキュメントのリアルタイム更新
- オンラインでテストできます
Swaggerは優れたツールであり、ほとんどすべての大企業で使用されており、反復開発のニーズにより適合しています。
【注意】正式リリースの際は、スワッガーを閉じてください!!!安全上の理由から。そして、実行中のメモリを節約します。