web接口開發時在調試階段最麻煩的就是參數調試，前端需要咨詢后端。后端有時候自己也不是很了解。這時候就會造成調試一次接口就需要看一次代碼。Swagger幫我們解決對接的麻煩
springboot接入swagger
- springboot 引入swagger只需要引入jar包，然后配置swagger啟動。並配合swagger的注解使用就可以實現文檔自動生成了。我們先來看看效果
環境准備
-
代碼還是基於spring倉庫開發。分支為
feature/0004/springboot-swagger -
swagger.version=2.9.2
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
配置
@Configuration
@EnableSwagger2
public class SwaggerConfig2 {
@Bean
public Docket createRestApi() {
// 添加請求參數，我們這里把token作為請求頭部參數傳入后端
ParameterBuilder parameterBuilder = new ParameterBuilder();
List<Parameter> parameters = new ArrayList<Parameter>();
parameterBuilder.name("token").description("令牌")
.modelRef(new ModelRef("string")).parameterType("header").required(false).build();
parameters.add(parameterBuilder.build());
return new Docket(DocumentationType.SWAGGER_2)
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("com"))
.paths(Predicates.not(PathSelectors.regex("/error.*")))
.build().apiInfo(new ApiInfoBuilder()
.title("后端服務說明")
.description("SpringBoot整合Swagger，詳細信息......")
.version("1.0")
.contact(new Contact("zxhtom", "zxhtom.blog.csdn.net", "870775401@qq.com"))
.license("The Apache License")
.licenseUrl("http://zxhtom.gitee.io")
.build())
.useDefaultResponseMessages(false)
.securitySchemes(securitySchemes())
.securityContexts(securityContexts())
.globalOperationParameters(parameters);
}
private List<ApiKey> securitySchemes() {
List<ApiKey> apiKeyList = new ArrayList();
apiKeyList.add(new ApiKey("Authorization", "token", "header"));
return apiKeyList;
}
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(
SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("^(?!auth).*$"))
.build());
return securityContexts;
}
List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
}
添加請求頭
securitySchemes(securitySchemes())
securityContexts(securityContexts())
- 在上面的兩端配置就是加入全局的token設置的。在swagger-ui界面顯示是右上角有一把鎖的標志
接口使用
注解使用
| 注解 | 功能 |
|---|---|
| @Api() | 用在請求的類上。表示該類的請求類用於文檔標注 |
| @ApiOperation() | 用於方法上。對一個http請求的具體說明，出參入參說明 |
| @ApiModel() | 對請求實體的一個說明 |
| @ApiModelProperty | 對實體內屬性說明，也可以設置默認值 |
| @ApiImpliciParams() | 用於請求的方法上，里面是ApiImpliciParam數組 |
| @ApiImpliciParam() | 表示單獨請求參數。可以設置form表單中參數單獨設置 |
| @ApiParam() | 對請求方法中參數的單獨設置 類似ApiImpliciParam |
| @ApiResponses() | 對請求方法上根據響應碼設置說明 |
| @ApiResponse | 單個響應碼說明 |
| @ApiIgnore() | 對該請求的忽略 |
- 具體使用可以查看源碼。源碼上面有給出。
自定義swaggerUI
- 這里需要首先介紹下spring資源的加載順序。
src/main/resources/META-INF/resources
src/main/resources/static
src/main/resources/public
- 這三個優先級依次降低。歡句話說spring首先會在src/main/resources/META-INF/resources下尋找資源。所以這也是我們自定義swaggerUI的策略。我們只需要在META-INF下重新繪畫swaggerUI的頁面就行了。這里只是提供思路。不具體實現(懶)
# 加入戰隊
微信公眾號
