1.pomファイルにSwagger3依存関係を導入します
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2.Swagger3Config構成クラスを記述します
package com.infoshare.config;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
//@EnableSwagger2 是 swagger2.0版本的注解
//swagger在3.0之后换成了@EnableOpenApi
@Configuration
@EnableOpenApi
public class Swagger3Config {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("Swagger3接口文档")
.description("适用于前后端分离统一的接口文档")
.version("1.0")
.build();
}
}
3.Swagger3.0で一般的に使用される注釈
@Api:要求されたクラスで使用されます。これは、クラスの説明を意味します。tags
= "クラスの機能を説明するためにUIインターフェイスに表示されるアノテーション"
value = "このパラメーターは無意味であり、次のようにも表示されます。 UIインターフェース上にあるので、設定する必要はありません。」@ApiOperation:リクエストされたメソッドで使用され、メソッドの目的と機能を説明し
ますvalue = "メソッドの目的と機能を説明します"
notes = "メソッドに関する注意"@ApiImplicitParams:パラメーターの説明のセットを示すためにrequestメソッドで使用されます
@ApiImplicitParam:リクエストのすべての側面を指定するために@ApiImplicitParamsアノテーションで使用されますパラメーター
名:パラメーター名
値:
必要なパラメーターの中国語の文字の説明と説明:かどうかパラメータを渡す必要があります
paramType:パラメータを配置する場所
・ヘッダー->リクエストパラメータの取得:@RequestHeader
・クエリ->リクエストパラメータの取得:@RequestParam
・パス(安らかなインターフェイスの場合)->リクエストパラメータの取得:@PathVariable
・div(一般的には使用されません)
・form(一般的に使用されません)
dataType:パラメーターの種類、デフォルトの文字列、その他の値dataType = "Integer"
defaultValue:パラメーターのデフォルト値@ApiResponses:一連の応答を表すためにrequestメソッドで
使用されます@ApiResponse:@ApiResponsesで使用され、通常、誤った応答メッセージ
コードを表すために使用され
ます:400メッセージなどの番号:「要求パラメーターが入力されていません」などの情報"
応答:例外をスローしたクラス@ApiModel:応答データを返すメッセージを示すために応答クラスで使用されます(これは通常、投稿が作成されたとき
の@ RequestBody、@ ApiImplicitParamアノテーションを使用して要求パラメーターを記述できない場合などのシナリオで使用されます)
@ApiModelProperty: On属性を使用して、応答クラスの属性を記述します
4.コントローラーレイヤーはSwagger3アノテーションの例を使用します
package com.infoshare.controller;
import com.infoshare.service.IUserService;
import com.infoshare.util.SendMailUtil;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.scheduling.annotation.Async;
import javax.annotation.Resource;
import javax.servlet.http.HttpSession;
/**
* @author: RJC
* @time: 2020/9/12
*/
@Api(tags = "用户信息处理")
@RestController
@RequestMapping("/user")
public class UserController {
@Resource(name = "userServiceImpl")
private IUserService userService;
@Resource(name = "sendMailUtil")
private SendMailUtil sendMailUtil;
private final static int AUTH_CODE_VALID_TIME = 600; //验证码失效时间为 10 min
/**
* 异步获得验证码的接口
* 验证码存储到 Session 里面
* @param mail 邮箱
* @return authCode_
*/
@ApiOperation("用户获得注册验证码")
@Async
@GetMapping("/getAuthCode")
public String getAuthCode(@RequestParam(name = "mail") String mail,
HttpSession session){
String authCode_ = sendMailUtil.sendMailAndGetAuthCode(mail);
session.setAttribute("mail",authCode_);
session.setMaxInactiveInterval(AUTH_CODE_VALID_TIME); //设置验证码失效时间为10min
return authCode_;
}
}
5.Swagger3インターフェイスのドキュメントインターフェイスにアクセスします
Swaggerのアクセスパスがport / swagger-ui.htmlからport / swagger-ui /またはport / swagger-ui /index.htmlに変更されます
。2つのアクセス方法のいずれかを選択します。
localhost:8080/swagger-ui/
localhost:8080/swagger-ui/index.html
6.Swagger3インターフェースドキュメントインターフェース表示