Swagger

一個規范完整的框架

用以生成,描述,調用和可視化

主要作用為

自動生成接口文檔

方便后端開發進行接口調試

Knife4j

為Java MVC框架集成

依賴引入:

<!--  knife4j版接口文檔 訪問/doc.html-->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>

Swagger配置類

構建了指定相關信息的接口文檔

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import com.zzyl.properties.SwaggerConfigProperties;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.actuate.autoconfigure.endpoint.web.CorsEndpointProperties;
import org.springframework.boot.actuate.autoconfigure.endpoint.web.WebEndpointProperties;
import org.springframework.boot.actuate.autoconfigure.web.server.ManagementPortType;
import org.springframework.boot.actuate.endpoint.ExposableEndpoint;
import org.springframework.boot.actuate.endpoint.web.*;
import org.springframework.boot.actuate.endpoint.web.annotation.ControllerEndpointsSupplier;
import org.springframework.boot.actuate.endpoint.web.annotation.ServletEndpointsSupplier;
import org.springframework.boot.actuate.endpoint.web.servlet.WebMvcEndpointHandlerMapping;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.core.env.Environment;
import org.springframework.util.StringUtils;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;import java.util.ArrayList;
import java.util.Collection;
import java.util.List;@Configuration
@EnableConfigurationProperties(SwaggerConfigProperties.class)
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {@AutowiredSwaggerConfigProperties swaggerConfigProperties;@Bean(value = "defaultApi2")@ConditionalOnClass(SwaggerConfigProperties.class)public Docket defaultApi2() {// 構建API文檔  文檔類型為swagger2return new Docket(DocumentationType.SWAGGER_2).select()// 配置 api掃描路徑.apis(RequestHandlerSelectors.basePackage(swaggerConfigProperties.getSwaggerPath()))// 指定路徑的設置  any代表所有路徑.paths(PathSelectors.any())// api的基本信息.build().apiInfo(new ApiInfoBuilder()// api文檔名稱.title(swaggerConfigProperties.getTitle())// api文檔描述.description(swaggerConfigProperties.getDescription())// api文檔版本.version("1.0") // 版本// api作者信息.contact(new Contact(swaggerConfigProperties.getContactName(),swaggerConfigProperties.getContactUrl(),swaggerConfigProperties.getContactEmail())).build());}/*** 增加如下配置可解決Spring Boot 6.x 與Swagger 3.0.0 不兼容問題**/@Beanpublic WebMvcEndpointHandlerMapping webEndpointServletHandlerMapping(WebEndpointsSupplier webEndpointsSupplier,ServletEndpointsSupplier servletEndpointsSupplier,ControllerEndpointsSupplier controllerEndpointsSupplier,EndpointMediaTypes endpointMediaTypes,CorsEndpointProperties corsProperties,WebEndpointProperties webEndpointProperties,Environment environment) {List<ExposableEndpoint<?>> allEndpoints = new ArrayList();Collection<ExposableWebEndpoint> webEndpoints = webEndpointsSupplier.getEndpoints();allEndpoints.addAll(webEndpoints);allEndpoints.addAll(servletEndpointsSupplier.getEndpoints());allEndpoints.addAll(controllerEndpointsSupplier.getEndpoints());String basePath = webEndpointProperties.getBasePath();EndpointMapping endpointMapping = new EndpointMapping(basePath);boolean shouldRegisterLinksMapping = this.shouldRegisterLinksMapping(webEndpointProperties, environment, basePath);return new WebMvcEndpointHandlerMapping(endpointMapping, webEndpoints, endpointMediaTypes, corsProperties.toCorsConfiguration(),new EndpointLinksResolver(allEndpoints, basePath), shouldRegisterLinksMapping, null);}private boolean shouldRegisterLinksMapping(WebEndpointProperties webEndpointProperties, Environment environment, String basePath) {return webEndpointProperties.getDiscovery().isEnabled() && (StringUtils.hasText(basePath) || ManagementPortType.get(environment).equals(ManagementPortType.DIFFERENT));}
}

Swagger的常用注解

@Api//用在類上,用以描述控制類的作用
@ApiOperation//用在方法上,用以描述接口的作用
@ApiParam//用在方法上描述單個參數的含義
@ApilmplicitParam//描述單個形參
@ApilmplicitParams//描述多個形參
@ApiModel//用在實體類上描述實體類
@ApiModelProperty//用在實體類的屬性上描述實體類的字段含義

訪問對應后端ip加端口/doc.html即可訪問接口文檔