Swagger-springboot整合

最新推荐文章于 2023-06-15 10:13:49 发布

上海程序员-紫枫

最新推荐文章于 2023-06-15 10:13:49 发布

阅读量143

点赞数 1

分类专栏： Swagger java 文章标签： java swagger

本文链接：https://blog.csdn.net/tian6318/article/details/98518867

版权

java 同时被 2 个专栏收录

8 篇文章 0 订阅

订阅专栏

Swagger

2 篇文章 0 订阅

订阅专栏

Swagger 作为一个强大的API文档工具深受广大开发者的喜爱，今天主要做个 springboot 整合 swagger的 demo
方便初学者学习参考

新建一个springboot 项目

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>

	<groupId>com.cloud</groupId>
	<artifactId>swagger-ui</artifactId>
	<version>1.0.0</version>
	<packaging>war</packaging>

	<name>swagger-ui</name>
	<description>swagger Spring Boot</description>

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>1.5.10.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>

	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
		<java.version>1.8</java.version>
		<!--lombok-->
        <lombok.version>1.16.16</lombok.version>
	</properties>

	<dependencies>
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger2</artifactId>
		    <version>2.8.0</version>
		</dependency>
		<dependency>
		    <groupId>com.github.xiaoymin</groupId>
		    <artifactId>swagger-bootstrap-ui</artifactId>
		    <version>1.9.5</version>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-tomcat</artifactId>
			<scope>provided</scope>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
		<!--lombok-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${lombok.version}</version>
        </dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>
</project>

其中 springfox-swagger2 为核心JAR包

<dependency>
   <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>

swagger-bootstrap-ui 为页面展示JAR包，包含前端文件，如果喜欢不同的风格可以自行替换

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.5</version>
</dependency>

新增SwaggerConfiguration 配置文件，配置需要展示的接口文档信息，代码如下：

package com.cloud.configuration;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

import com.google.common.collect.Sets;

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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration extends WebMvcConfigurationSupport{
	
	
	@Bean
    public Docket userRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("用户相关接口文档")
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                .produces(Sets.newHashSet("application/json"))
                .consumes(Sets.newHashSet("application/json"))
                .protocols(Sets.newHashSet("http", "https"))
                .apiInfo(userApiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.cloud.controller.user"))
                .paths(PathSelectors.any())
                .build();
    }
	
	@Bean
    public Docket orderRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("订单相关接口文档")
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                .produces(Sets.newHashSet("application/json"))
                .consumes(Sets.newHashSet("application/json"))
                .protocols(Sets.newHashSet("http", "https"))
                .apiInfo(userApiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.cloud.controller.order"))
                .paths(PathSelectors.any())
                .build();
    }
	
	@Bean
	public ApiInfo userApiInfo() {
		return new ApiInfoBuilder()
				.title("用户相关接口")
				.description("包含用户XXXXXX相关功能")
				.contact(new Contact("接口域名", "www.test.com", "abc@163.com"))
				.version("1.0.0")
				.build();
	}
	
	@Bean
	public ApiInfo orderApiInfo() {
		return new ApiInfoBuilder()
				.title("订单相关接口")
				.description("包含订单XXXXXX相关功能")
				.contact(new Contact("接口域名", "www.test.com", "abc@163.com"))
				.version("1.0.0")
				.build();
	}
	
	@Override
	protected void addResourceHandlers(ResourceHandlerRegistry registry) {
		//解决swagger无法访问
		registry.addResourceHandler("/doc.html")
				.addResourceLocations("classpath:/META-INF/resources/");
		// 解决swagger的js文件无法访问
		registry.addResourceHandler("/webjars/**")
				.addResourceLocations("classpath:/META-INF/resources/webjars/");
	}
	
}

接着我们开始编写接口的请求参数，响应参数，方式有很多种，这里采用比较简单通用的一种
编写Result，实现rest接口的通用参数

@Data
@ApiModel(description = "Result")
public class Result<T> {
	
	@ApiModelProperty(value = "结果码", readOnly = true, required = true)
	private Integer code;
	
	@ApiModelProperty(value = "结果描述", readOnly = true, required = true)
	private String message;
	
	@ApiModelProperty(value = "数据体", readOnly = true, required = true)
	private T data;
	
	public static <T> Result<T> success(T t, String message) {
		Result<T> result = new Result<>();
		result.setCode(0);
		result.setMessage(message);
		result.setData(t);
		return result;
	}
	
	public Boolean checkSuccess() {
		return code != null && code.intValue() == 200;
	}
	
}

接着我们就开始模拟写一个接口，代码很简单，直接给出
请求参数：

@Data
@ApiModel(description = "用户请求")
public class UserRequest {

	@ApiModelProperty(value = "姓名", required = true)
	private String name;
	
	@ApiModelProperty(value = "性别", required = true)
	private Integer sex;
	
	@ApiModelProperty(value = "年龄", required = true)
	private Integer age;
}

响应参数：

@Data
@Builder
@ApiModel(description = "用户信息")
public class UserInfo {

	@ApiModelProperty(value = "姓名", readOnly = true, required = true)
	private String name;
	
	@ApiModelProperty(value = "性别", readOnly = true, required = true)
	private Integer sex;
	
	@ApiModelProperty(value = "年龄", readOnly = true, required = true)
	private Integer age;
}

定义接口：

@RestController
@RequestMapping(value = "/userService")
@Api(value = "用户服务", description = "用户服务")
public class UserController {

	
	@ApiOperation(value = "新增用户信息")
	@RequestMapping(value = "add", method = RequestMethod.POST)
	public Result<UserInfo> add(@RequestBody UserRequest request) {
		UserInfo userInfo = UserInfo.builder()
								.name(request.getName())
								.sex(request.getSex())
								.age(request.getAge())
								.build();
		return Result.success(userInfo, "调用成功！");
	}
}

编写启动类：SwaggerUiApplication

package com.cloud;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SwaggerUiApplication {

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