Swagger is a standardized and complete framework for generating, describing, calling, and visualizing RESTful-style web services. The overall goal is to make the client and file system update at the same speed as the server. File methods, parameters and models are tightly integrated into server-side code, allowing the API to always keep synchronized.
Swagger has never been easier to deploy and manage and use powerful APIs. OK, the above is the official statement, I copied it directly. In my opinion, swagger is an interface document manager. In the past, we usually wrote interfaces in the world, but there is a problem that we need to rely on third-party tools when testing. The GET interface is okay, and it is opened directly by the browser. POST can only rely on other tools. Swagger can directly generate interface documents (JavaEE) through the annotations in the code. Most people use this method, and it is directly integrated into the project to facilitate members to view, and can also test directly. In addition, the interface of Swagger is also good. Maybe this is why I chose to use Swagger. The RESTful style that is directly mentioned by the official is not RESTful. Style interfaces can also be used. Of course, there is another way for Swagger to write interface instructions manually. The advantage is that the code only has code, because once the Swagger interface annotation is added to the code, the amount of code still increases a lot. Of course, the disadvantage is that after you have modified the code, you have to change the interface document.
SpringMVC is very simple to integrate springfox-swagger2 and springfox-swagger-ui, only two steps:
(1) Add dependencies in pom
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${springfox-swagger.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${springfox-swagger.version}</version> </dependency>(2) Add Swagger configuration class:
@Configuration @EnableSwagger2 @EnableWebMvc @ComponentScan("com.XXX.controller") public class SwaggerConfig{ } Then you can see all the interface information in the project through http://localhost/swagger-ui.html, and you can see the json data through http://localhost/v2/api-docs.
But how do I disable these API documents in a production environment? I tried many ways and finally found a simple and practical method:
@Configuration @EnableSwagger2 @EnableWebMvc @ComponentScan("com.XXX.controller") public class SwaggerConfig{ @Autowired ConfigService configService; @Bean public Docket customDocket() { if(configService.getServerEnv() == ServerEnvEnum.ONLINE) { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfoOnline()) .select() .paths(PathSelectors.none())//If it is an online environment, add path filtering and set to none of them comply with .build(); }else { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()); } } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("XXX System") .description("XXX System Interface") .license("") .licenseUrl("") .termsOfServiceUrl("") .version("1.0.0") .contact(new Contact("","", "")) .build(); } private ApiInfo apiInfoOnline() { return new ApiInfoBuilder() .title("") .description("") .license("") .licenseUrl("") .termsOfServiceUrl("") .version("") .contact(new Contact("","", "")) .build(); } } Although the page http://localhost/swagger-ui.html can still be accessed, there is no content, including http://localhost/v2/api-docs.
There should be a better way!
Reference: //www.VeVB.COM/article/135312.htm
Swagger must be in the same context as springmvc, springmvc is just a subcontext of spring. If swagger makes spring context load, then those swagger's urls cannot be intercepted with springmvc interceptor!
So, there are two solutions:
If using annotations:
(1) Spring-mvc configuration:
<!-- Use Annotation to automatically register a bean, scan only @Controller --> <context:component-scan base-package="com.inspur.eyun.yunbx" use-default-filters="false"><!-- base-package If multiple, separate with "," --> <context:include-filter type="annotation" expression="org.springframework.steretype.Controller"/> <context:include-filter type="assignable" expression="com.inspur.eyun.yunbx.swagger.SwaggerConfig"/> </context:component-scan>
Note that you need to add the swagger configuration, and at the same time:
(2) Spring configuration:
<!-- Package scanning, annotation related--> <context:component-scan base-package="com.inspur.eyun.yunbx"> <context:exclude-filter type="annotation" expression="org.springframework.steretype.Controller"/> <context:exclude-filter type="assignable" expression="com.inspur.eyun.yunbx.swagger.SwaggerConfig"/> </context:component-scan>
Pay attention to excluding swagger
(3) Swagger configuration:
@Configuration @EnableSwagger2 @EnableWebMvc @ComponentScan("com.inspur.eyun.yunbx.controller") public class SwaggerConfig{ }Note the @Configuration annotation.
Of course, the more recommended method is to use the XML configuration method, because this way you don't need to introduce the swagger dependency package:
(1) Spring-mvc configuration:
<!-- Use Annotation to automatically register a bean, scan only @Controller --> <context:component-scan base-package="com.inspur.eyun.yunbx" use-default-filters="false"><!-- base-package If multiple, separate with "," --> <context:include-filter type="annotation" expression="org.springframework.stereotype.Controller"/> </context:component-scan> <import resource="classpath:spring-mvc-swagger.xml" />
spring-mvc-swagger.xml:
<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> <description>SpringMVC Swagger Configuration</description> <!-- swagger configuration, production environment empty --> <bean /> </beans>
Note: We place swagger in a configuration file separately. If it is an online environment, the file content is empty. If it is an offline test environment, swagger is configured.
(2) Spring configuration:
<!-- Package scanning, annotation related--> <context:component-scan base-package="com.inspur.eyun.yunbx"> <context:exclude-filter type="annotation" expression="org.springframework.stereotype.Controller"/> </context:component-scan>
(3) Swagger configuration:
@EnableSwagger2 @EnableWebMvc public class SwaggerConfig{ @Bean public Docket customDocket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.inspur.eyun.yunbx.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("XXX Platform") .description("XXX Platform Interface") .license("") .licenseUrl("") .termsOfServiceUrl("") .version("1.0.0") .contact(new Contact("","", "")) .build(); } }Note: Here we removed @Configuration, and at the same time, we modified our pom and configured multiple profile packaging:
pom.xml:
<!-- Swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${springfox-swagger.version}</version> <scope>${swagger.scope}</scope> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <scope>${swagger.scope}</scope> <version>${springfox-swagger-ui.version}</version> </dependency>Note: The scope dependent here is set dynamically. If it is an online environment, we can set the scope to provided.
<profiles> <profile> <id>dev</id> <properties> <profiles.active>dev</profiles.active> <swagger.scope>compile</swagger.scope> </properties> <activation> <activeByDefault>true</activeByDefault> </activation> </profile> <profile> <id>test</id> <properties> <profiles.active>test</profiles.active> <swagger.scope>compile</swagger.scope> </properties> </profile> <profile> <id>online</id> <properties> <properties> <profiles.active>test</profiles.active> <swagger.scope>compile</swagger.scope> </properties> </profile> <profile> <id>online</id> <properties> <profiles.active>online</profiles.active> <swagger.scope>provided</swagger.scope> </properties> </profile> </profiles> </profiles>
Set different scopes for swagger's dependencies through different profiles!
Note: There is a bug in springfox-swagger.version=2.7.0, and you can use the lower version 2.6.1. Too fucking trick!
The above is all the content of this article. I hope it will be helpful to everyone's learning and I hope everyone will support Wulin.com more.