springboot整合swagger2+跨域问题

前言

本篇文章主要介绍的是springboot整合swagger2。
swagger2是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务，这里介绍两种方式实现，第一种是在yml中添加配置，第二种是添加配置类。

GitHub源码链接位于文章底部。

工程结构

首先来看一下工程结构

引入依赖

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.3.RELEASE</version>
    </parent>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
        <!-- swagger Restful API -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>
    </dependencies>

swagger Restful API的两个依赖可以由下面这个依赖代替，使用这两种依赖的swagger-ui界面会有一些不同，但使用方法是一样的，此外，类上的Api注解中的值，上面这种为value,下面这种为tags：

        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.7.0.RELEASE</version>
        </dependency>

第一种方式：在yml中添加swagger中配置,然后在启动类上添加EnableSwagger2Doc注解

这种方式只能使用swagger-spring-boot-starter依赖，因为只有它才有EnableSwagger2Doc注解。

####swagger相关配置
swagger:
  base-package: com.lxg.controller
  title: Spring Boot中使用Swagger2构建RESTful APIs
  description: swagger2-文档构建利器
  version: 1.7
  terms-of-service-url: www.lxgblog.com
  contact:
    name: LXG
    email: 15279295097@163.com

第二种方式：定义swagger配置类

springboot使用Swagger很简单，只需要使用Configuration注解配合Bean注解将一些配置注入到spring容器，比如编辑Swagger UI界面的信息，指定Swagger负责扫描的package等等，然后在该配置类上添加EnableSwagger2注解开启即可。

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //定义扫描接口的包
                .apis(RequestHandlerSelectors.basePackage("com.lxg.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //定义界面标题
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                //定义界面描述
                .description("swagger2-文档构建利器")
                .termsOfServiceUrl("https://www.lxgblog.com/")
                //作者
                .contact("李先国")
                //版本
                .version("1.0")
                .build();
    }
}

因为这里只做测试用，所以就不连接数据库，写到控制层即可。

实体类

@Data
public class User {
    private Long id;
    /** 姓名 */
    private String name;

    /** 年龄 */
    private Integer age;

    public User() {
    }

    public User(Long id, String name, Integer age) {
        this.id = id;
        this.name = name;
        this.age = age;
    }
}

Controller 控制层

因为swagger作用于接口，它通过注解来实现配置，所以我们在控制层添加一些方法，就能将对应接口显示到swagger-ui上。

@RestController
@RequestMapping(value = "/api")
@Api(value="用户操作接口")
public class UserController {
	/**
	 * @ApiOperation注解来给API增加说明、通过@ApiParam注解来给参数增加说明。
	 * value 是标题,notes是详细说明
	 * @param user
	 * @return
	 */
	@ApiOperation(value="创建用户", notes="根据User对象创建用户")
	@PostMapping("/user")
    public Map<String, Object> insert(@ApiParam(value = "用户详细实体user", required = true)@RequestBody User user) {
		Map<String, Object> map = new HashMap<>(16);
		map.put("respMsg", "新增成功");
		map.put("respData", user);
		map.put("respCode", 200);
		return map;
    }
    
	@ApiOperation(value="更新用户", notes="根据User对象更新用户")
	@PutMapping("/user")
    public Map<String, Object>  update(@ApiParam(value = "用户详细实体user", required = true)@RequestBody User user) {
		Map<String, Object> map = new HashMap<>(16);
		map.put("respMsg", "更新成功");
		map.put("respData", user);
		map.put("respCode", 200);
		return map;
    }
	
	@ApiOperation(value="删除用户", notes="根据id删除用户")
	@DeleteMapping("/user/{id}")
    public Map<String, Object> delete(@ApiParam(value = "用户id", required = true) @PathVariable Integer id)  {
		Map<String, Object> map = new HashMap<>(16);
		map.put("respMsg", "删除成功");
		map.put("respCode", 200);
		map.put("id", id);
		return map;
    }

	@ApiOperation(value="获取用户列表", notes="根据User对象查询用户信息")
    @GetMapping("/user")
    public List<User> findByUser() {
		List<User> list = new ArrayList<>();
		list.add(new User(1L,"张三",18));
		list.add(new User(2L,"李四",20));
        return list;
    }
}

Api注解：作用于类上，作用是对该类进行说明，说明的信息由value的值决定。
ApiOperation注解： 作用于方法上作用是对该接口进行说明，value是接口名称，notes是说明。
ApiParam注解：作用于参数，对方法参数进行说明。

application.yml配置文件

server:
  port: 8080

启动类

@SpringBootApplication
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
}

测试

启动程序后，访问http://localhost:8080/swagger-ui.html 即可查看页面

可以看到代码里通过注解写的说明都在页面上体现出来了。

接下来看http请求测试，将在图中进行说明：

get请求

post请求

delete请求，url带动态id

跨域问题

跨域是什么？浏览器从一个域名的网页去请求另一个域名的资源时，域名、端口、协议任一不同，都是跨域 。我们是采用前后端分离开发的，也是前后端分离部署的，必然会存在跨域问题。怎么解决跨域？
这里介绍两种方式，
1.只需要在 controller 类上添加注解CrossOrigin即可！这个注解其实是 CORS 的实现。
2.添加配置类：

@Configuration
public class WebMvcConfiguration implements WebMvcConfigurer{
    @Bean
    public CorsFilter corsFilter() {
        final UrlBasedCorsConfigurationSource urlBasedCorsConfigurationSource = new UrlBasedCorsConfigurationSource();
        final CorsConfiguration corsConfiguration = new CorsConfiguration();
        /*是否允许请求带有验证信息*/
        corsConfiguration.setAllowCredentials(true);
        /*允许访问的客户端域名*/
        corsConfiguration.addAllowedOrigin("*");
        /*允许服务端访问的客户端请求头*/
        corsConfiguration.addAllowedHeader("*");
        /*允许访问的方法名,GET POST等*/
        corsConfiguration.addAllowedMethod("*");
        urlBasedCorsConfigurationSource.registerCorsConfiguration("/**", corsConfiguration);
        return new CorsFilter(urlBasedCorsConfigurationSource);
    }
}

本文GitHub源码：https://github.com/lixianguo5097/springboot/tree/master/springboot-swagger

CSDN：https://blog.csdn.net/qq_27682773
简书：https://www.jianshu.com/u/e99381e6886e
博客园：https://www.cnblogs.com/lixianguo
个人博客：https://www.lxgblog.com