目錄
一、Swagger2完整用法
1.POM依賴
2.接口類
3.實(shí)現(xiàn)類
4.托管靜態(tài)資源
5.接口文檔配置
6.生產(chǎn)環(huán)境關(guān)閉接口文檔
7.Swagger3頁面效果
二、Swagger3完整用法
三、Swagger整合Knife4jUi
1.POM依賴
2.接口類
3.實(shí)現(xiàn)類
4.托管靜態(tài)資源
5.接口文檔配置
6.生產(chǎn)環(huán)境關(guān)閉接口文檔
四、注釋和參數(shù)講解
1.@Api()
2.@ApiOperation()
3.@ApiParam()
4.@ApiModel()
5.@ApiModelProperty()
6.@ApiImplicitParams() 和@ApiImplicitParam()
Swagger 說明
Swagger是為了解決企業(yè)中接口（api）中定義統(tǒng)一標(biāo)準(zhǔn)規(guī)范的文檔生成工具。方便各大后端小基友的懶問題，但是寫注解也是妥妥的麻煩，但是如果版本迭代快或者人員的流動(dòng)性大，會(huì)導(dǎo)致很多問題。所以很多企業(yè)中都會(huì)有統(tǒng)一的規(guī)范文檔，來定義接口標(biāo)準(zhǔn)。
一、Swagger2完整用法
1.POM依賴
<properties>
? ?<springfox-swagger.version>2.9.2</springfox-swagger.version>
</properties>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${springfox-swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${springfox-swagger.version}</version>
</dependency>2.接口類
見【3.2】
3.實(shí)現(xiàn)類
見【3.3】
4.托管靜態(tài)資源
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
@EnableSwagger2
@EnableWebMvc
@Configuration
public class ApiDocConfiguration extends WebMvcConfigurerAdapter {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
super.addResourceHandlers(registry);
}
}5.接口文檔配置
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.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class SwaggerConf {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()).enable(true)
.select()
.apis(RequestHandlerSelectors.basePackage("com.ikong.service.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("開放接口平臺(tái)")
.description("")
.contact(new Contact("ikong", "http://ikong.ik.com", "ikong@ik.com"))
.version("1.0")
.build();
}
}6.生產(chǎn)環(huán)境關(guān)閉接口文檔
見【3.6】
7.Swagger3頁面效果
Swagger2多包實(shí)現(xiàn)方法
二、Swagger3完整用法
1.POM依賴
2.接口類
3.實(shí)現(xiàn)類
4.托管靜態(tài)資源
5.接口文檔配置
6.生產(chǎn)環(huán)境關(guān)閉接口文檔
7.Swagger3頁面效果
三、Swagger整合Knife4jUi
1.POM依賴
<properties>
? ? <knife4j-swagger.version>3.0.3</knife4j-swagger.version>
</properties>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>${knife4j-swagger.version}</version>
</dependency>
2.接口類
import com.ikong.model.req.TestReq;
import com.ikong.model.ret.TestRet;
import com.jd.security.framework.common.model.Result;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;
public interface TestApi {
String test1(@RequestParam(value = "name") String name);
TestRet test2(@RequestBody TestReq req);
Result<TestRet> test3(@RequestBody TestReq req);
}3.實(shí)現(xiàn)類
import com.ikong.api.TestApi;
import com.ikong.model.req.TestReq;
import com.ikong.model.ret.TestRet;
import com.jd.security.framework.common.model.Result;
import com.jd.security.framework.common.model.ResultUtils;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
@Api(tags = "驗(yàn)證參數(shù)類型")
@RestController
@RequestMapping("/test")
public class TestApiController implements TestApi {
@ApiOperation("001接收普通參數(shù)")
@ApiImplicitParam(name = "name", value = "姓名", required = true)
@GetMapping("test1")
@Override
public String test1(@RequestParam(value = "name") String name) {
return "hello," + name;
}
@ApiOperation("002接收對(duì)象參數(shù)")
@GetMapping("test2")
@Override
public TestRet test2(TestReq req) {
return new TestRet(Long.valueOf(req.getId()), 200);
}
@ApiOperation("003返回標(biāo)準(zhǔn)格式")
@PostMapping("test3")
@Override
public Result<TestRet> test3(@RequestBody TestReq req) {
return ResultUtils.wrapSuccess(new TestRet(Long.valueOf(req.getId()), 200));
}
}4.托管靜態(tài)資源
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
@Configuration
public class ApiDocHandlerConfiguration extends WebMvcConfigurationSupport {
@Value("${swagger.enable:true}")
private Boolean enable = false;
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
if (enable) {
registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
}
5.接口文檔配置
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
import java.util.ArrayList;
import java.util.List;
@Configuration
@EnableSwagger2WebMvc
public class ApiDocKnife4jUiConfig {
@Bean
public Docket docket(Environment environment) {
// 添加接口請(qǐng)求頭參數(shù)配置 沒有的話 可以忽略
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<>();
tokenPar.name("token")
.description("令牌")
.defaultValue("")
.modelRef(new ModelRef("string"))
.parameterType("header").required(false).build();
pars.add(tokenPar.build());
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(true)//是否啟動(dòng)swagger 默認(rèn)啟動(dòng)
.groupName("ikong")//所在分組
.select()
.apis(RequestHandlerSelectors.basePackage("com.ikong.service.impl"))//指定掃描的包路徑
.paths(PathSelectors.any())
.build()
.globalOperationParameters(pars);
}
private ApiInfo apiInfo() {
Contact author = new Contact("ikong", "api.ik.com", "ikong@ik.com");
return new ApiInfo(
"開放平臺(tái)接口文檔",
"開放平臺(tái)接口文檔",
"1.0",
"",
author,
"",
"",
new ArrayList<>()
);
}
}6.生產(chǎn)環(huán)境關(guān)閉接口文檔
application.properties
swagger.enable=false
7.Knife4jUi頁面效果
URL :?http://localhost:8083/doc.html
四、注釋和參數(shù)講解
參數(shù)說明：
name -- 參數(shù)名
value --?參數(shù)說明
required -- 是否必須填寫
dataType -- 數(shù)據(jù)類型
paramType -- 參數(shù)類型
example -- 舉例
常用注解說明：
-
@Api()用于類；
表示標(biāo)識(shí)這個(gè)類是swagger的資源
-
@ApiOperation()用于方法；
表示一個(gè)http請(qǐng)求的操作
-
@ApiParam()用于方法，參數(shù)，字段說明；
表示對(duì)參數(shù)的添加元數(shù)據(jù)（說明或是否必填等）
-
@ApiModel()用于類
表示對(duì)類進(jìn)行說明，用于參數(shù)用實(shí)體類接收
-
@ApiModelProperty()用于方法，字段
表示對(duì)model屬性的說明或者數(shù)據(jù)操作更改
-
@ApiIgnore()用于類，方法，方法參數(shù)
表示這個(gè)方法或者類被忽略
-
@ApiImplicitParam() 用于方法
表示單獨(dú)的請(qǐng)求參數(shù)文章來源：http://www.zghlxwxcb.cn/news/detail-586202.html
-
@ApiImplicitParams() 用于方法，包含多個(gè) @ApiImplicitParam文章來源地址http://www.zghlxwxcb.cn/news/detail-586202.html
具體使用說明：
1.@Api()
···
@Api("測(cè)試用例1")
@Controller
public class swaggerTestUse(){
}
2.@ApiOperation()
···
@Api("測(cè)試用例1")
@Controller
public class swaggerTestUse(){
@ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger測(cè)試")
public void apiOperationSwaggerTest(){
}
}
3.@ApiParam()
···
@Api("測(cè)試用例1")
@Controller
public class swaggerTestUse(){
@ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger測(cè)試")
public void apiOperationSwaggerTest(@ApiParam(name = "id", value = "id入?yún)?, required = true) Integer id){
}
}
4.@ApiModel()
···
@ApiModel(description = "測(cè)試實(shí)體類", value = "測(cè)試實(shí)體類")
public class Album implements Serializable {
···
}
5.@ApiModelProperty()
···
@ApiModel(description = "測(cè)試實(shí)體類", value = "測(cè)試實(shí)體類")
public class User implements Serializable {
@ApiModelProperty(name = "userName", value = "用戶名", required = false, exmaple = "小明")
private String userName;
}
6.@ApiImplicitParams() 和@ApiImplicitParam()
···
@Api("測(cè)試用例1")
@Controller
public class swaggerTestUse(){
@ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger測(cè)試")
@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "id入?yún)?, required = true, dataType = "Integer", paramType = "query"),
@ApiImplicitParam(name = "brand", value = "brand", required = true, dataType = "BRAND", paramType = "body")
})
public void apiOperationSwaggerTest(Integer id, Brand band){
}
}
到了這里，關(guān)于Java技術(shù)-接口文檔-Swagger2&Swagger3&接口文檔UI整合的文章就介紹完了。如果您還想了解更多內(nèi)容，請(qǐng)?jiān)谟疑辖撬阉鱐OY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！
