フロントエンドとバックエンドの両方の開発は、インターフェイスドキュメントによって多かれ少なかれ拷問されていると思います。フロントエンドは、バックエンドによって提供されるインターフェイスドキュメントが実際の状況と一致しないと不平を言うことがよくあります。バックエンドでは、インターフェースドキュメントの作成と維持に多くのエネルギーが消費されると感じており、更新するには遅すぎることがよくあります。実際、フロントエンドがバックエンドを呼び出すか、バックエンドがバックエンドを呼び出すかに関係なく、優れたインターフェイスドキュメントが期待されます。
SpringBootに統合されたSwaggerは、非常に単純な注釈を通じてインターフェースを明確に記述し、ビジュアルドキュメントページを生成できます。
ネイティブのSwagger-uiインターフェースは非常に粗いため、代わりにknife4j-spring-uiを使用してください。
この記事のナビゲーション
優れたHTTPインターフェイスドキュメントの説明
- インターフェイスのリクエストパスを明確に記述します：QueryPath：/ user / login
- インターフェイスのリクエストメソッドタイプを明確に記述します：GET / POST / DELETE / PUT
- インターフェースのビジネス上の意味と使用シナリオを明確に書く
- インターフェースの入力パラメーターを明確に記述します：パラメーターの説明、パラメーターのタイプ、パラメーターの構造、パラメーターを渡す必要があるかどうか
- インターフェースの戻りタイプを明確に記述します：戻されたデータ構造、異常な状態
SpringBootがSwaggerを統合
プロジェクト導入依存
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-ui</artifactId>
<version>2.0.4</version>
</dependency>
Swagger構成に関するSpringBoot
このSwagger構成をプロジェクトに貼り付けるだけです
@EnableSwagger2
@Configuration
public class SwaggerConfig implements WebMvcConfigurer {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//这里改成自己的接口包名
.apis(RequestHandlerSelectors.basePackage("vip.codehome.springboot.tutorials.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot教程接口文档")//标题
.description("使用swagger文档管理接口")//描述
.contact(new Contact("codehome", "", "[email protected]"))//作者信息
.version("1.0.0")//版本号
.build();
}
//解决doc.html，swagger-ui.html 404问题
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations(
"classpath:/static/");
registry.addResourceHandler("swagger-ui.html").addResourceLocations(
"classpath:/META-INF/resources/");
registry.addResourceHandler("doc.html").addResourceLocations(
"classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations(
"classpath:/META-INF/resources/webjars/");
}
}
Swaggerの特定の使用法
各アノテーションの役割
- @Apiはクラスでのクラスの役割を紹介します
- @ApiOperationはメソッドを配置して、メソッドの役割を紹介します
- @ApiImplicitParamの紹介
- @ApiResponseは戻りステータスを導入します
- @ ApiModel、@ ApiModelPropertyはじめに入力パラメーターはオブジェクトで、戻り値はオブジェクトフィールドの説明です
コード例
@RestController
@Api(tags = "Swagger注解测试类")
public class SwaggerUserController {
@ApiOperation(value = "这是一个echo接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "msg",value = "请求的msg参数",required = true,paramType = "query"),
@ApiImplicitParam(name = "token",value = "请求的token",required = false,paramType ="header" )
})
@ApiResponses({
@ApiResponse(code=200,message = "请求成功"),
@ApiResponse(code=400,message="请求无权限")
})
@GetMapping("/echo")
public String echo(String msg,@RequestHeader(name = "token") String token){
return msg;
}
@PostMapping("/login")
public R<UserInfoVO> login(@RequestBody LoginDTO loginDTO){
UserInfoVO userInfoVO=new UserInfoVO();
userInfoVO.setNickname("编程之家");
userInfoVO.setToken("xxx");
return R.ok(userInfoVO);
}
}
@Data
@ApiModel
public class LoginDTO {
@ApiModelProperty(value = "用户账号或者邮箱")
String account;
@ApiModelProperty(value = "用户密码")
String passwd;
@ApiModelProperty(value = "用户密码")
String verifyCode;
}
インターフェースドキュメント効果
ここへの訪問はhttp：// localhost：8080 / doc.htmlです。knife4j-spring-uiには、元の機能よりも強力な機能があります。
千マイルは単一のステップから始まります。SpringBootチュートリアルシリーズの2番目の記事は、すべてのプロジェクトソースコードをGitHubからダウンロードできます。
