SPRINGMVC+SWAGGER整合

Posted 2021-05-01 blackcat1991

1、    Swagger简介

Swagger的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。

2、    springMvc整合Swagger

1、引入依赖

<dependency>
     <groupId>com.github.caspar-chen</groupId>
     <artifactId>swagger-ui-layer</artifactId>
     <version>0.0.3</version>
 </dependency>
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.6.0 </version>
 </dependency>

2、web.xml增加如下映射
注：数据来源于/v2/api-docs，并且返回的是json数据。

<servlet-mapping>
   <servlet-name>springServlet</servlet-name>
   <url-pattern>/v2/api-docs</url-pattern>
</servlet-mapping>

3、创建swagger配置文件类

package com.ai.ecs.swagger;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.Contact;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.List;

import static com.google.common.collect.Lists.newArrayList;

/**
 * @author blackcat
 * @create 2018-03-13 14:31
 */
@Configuration    // 配置注解，自动在本类上下文加载一些环境变量信息
@EnableSwagger2   // 使swagger2生效
@EnableWebMvc
@ComponentScan(basePackages = {"com.ai.ecs"})  //需要扫描的包路径
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()   // 选择那些路径和api会生成document
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())   // 对所有路径进行监控
                .build();
    }


    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return newArrayList(
                new SecurityReference("clientId", authorizationScopes),
                new SecurityReference("clientSecret", authorizationScopes),
                new SecurityReference("accessToken", authorizationScopes));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("huiI")
                .description("huiI interface define")
                .termsOfServiceUrl("https://wap.jx.10086.cn/hui/release/home/index.html")
                .contact(new Contact("hehb", "http://wwww.asiainfo.com", "[e-mail]"))
                .version("1.0.0").build();
    }
}

4、配置mvc：resource

<!-- 静态资源映射 -->
<mvc:resources location="classpath:/META-INF/resources/" mapping="docs.html"/>
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>

5、测试类

package com.ai.ecs.mall.web.demo;


import com.ai.ecs.mall.web.BaseController;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import redis.clients.jedis.JedisCluster;

import javax.servlet.http.HttpServletResponse;
import java.io.PrintWriter;


@Controller("testswagger")
@RequestMapping(value = "testswagger")
@Api(description="测试接口类")
public class TestController extends BaseController {

   @Autowired
   private JedisCluster jedisCluster;


   @RequestMapping(value = {"test"})
   @ApiOperation(value="测试方法",httpMethod="POST")
   public void test(String test,HttpServletResponse response) throws Exception{
      PrintWriter out =  response.getWriter();
      out.write(test);
      out.flush();
   }

}

5.界面截图
http://localhost:8082/huiI/docs.html

图注:大少公众号

3、Swagger注解

注解	描述	例子
@Api	作用于类名，描述controller类的功能	@Api(description = "代理商登录", tags = "AgentController")
@ApiOperation	作用于方法名，描述该方法的功能	@ApiOperation(value = "代理商登录", notes = "代理商登录")
@ApiModel	作用于实体类，描述实体类信息	@ApiModel("用户实体对象")
@ApiModelProperty	作用于实体类属性，描述该属性的信息	@ApiModelProperty(value = "用户标识", required = false, hidden = true)
@ApiImplicitParams	作用于方法，当入参来源比较复杂时（如果需要从header、parameter），可以用该属性声明	@ApiImplicitParams({ @ApiImplicitParam(paramType = "header", name = "userId", value = "用户标识，置于请求头中", type = "java.lang.Long", required = true), @ApiImplicitParam(paramType = "query", name = "username", value = "用户姓名，请求参数", type = "String", required = true), @ApiImplicitParam(paramType = "query", name = "age", value = "用户姓名，请求体中", type = "String", required = true), @ApiImplicitParam(paramType = "query", name = "gendar", value = "用户姓名", type = "String", required = true)})
@ ApiImplicitParam	为 @ApiImplicitParams的子项，逐一声明用户的入参信息	@ApiImplicitParam(paramType = "header", name = "userId", value = "用户标识，置于请求头中", type = "java.lang.Long", required = true)