Spring整合Swagger教程

原创已于 2022-11-21 00:16:43 修改 · 4.7k 阅读

22 ·

本内容遵循CC 4.0 BY-SA版权协议

标签

#spring #java #后端

于 2022-11-11 11:53:41 首次发布

本文档详细介绍了如何在SpringBoot项目中集成Swagger2，创建RESTful API文档。从添加依赖、下载Swagger-UI界面、配置Swagger、修改路径匹配策略到编写测试用例，每个步骤都有清晰的说明。最后展示了实现的效果，并提供了优化入口以方便快速访问自定义的API文档。

一.导入Swagger依赖

二.前往github下载swagger-ui界面

三.把下载好的swagger-ui-x.xx.x.zip里的dist文件拖到项目resources/static静态文件夹

四.填写Swagger配置类，最关键的一步

五.更改application.yml里的路径匹配策略

六.写测试案例

七.实现效果

一.导入Swagger依赖

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

二.前往github下载swagger-ui界面

地址:swagger下载地址

下载UI界面要对应OpenAPI版本，由于我用的是swagger2-3.0.0版本，所以用UI version4.X以上不影响

三.把下载好的swagger-ui-x.xx.x.zip里的dist文件拖到项目resources/static静态文件夹

这里不一定放到static文件夹里，可以根据自己目的存放文件夹位置

四.填写Swagger配置类，最关键的一步

大部分人运行不成功，是因为配置类写的不对的原因，这里一定要注意你用的是什么swagger版本，然后根据自己的版本配置，不同版本配置的参数会有一定的差异，然后就是扫描包，扫描包这里也要扫描对，如果扫描错了，UI页面那边只会显示No operations defined in spec!，扫描不清楚的可以参考swagger报错：No operations defined in spec! 解决方法_柳牧之的博客-CSDN博客

这里由于我用的是ApiOperation注解，所以我直接扫描ApiOperation注解类就行了。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.swagger.annotations.ApiOperation;
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;

/**
 * 
 * @author AWen
 * @date 2022年11月11日 
 */

@EnableSwagger2
@Configuration
public class SwaggerConfig {

	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.select()
				//扫描包，如果配置错误swagger页面会出现No operations defined in spec!
				.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
				.paths(PathSelectors.any())
				.build();
	}

	private ApiInfo apiInfo(){
		return new ApiInfoBuilder()
				.title("MES接口")
				.description("接口文档")
				.contact(new Contact("阿文","http://xiewenwen.top","921124136@qq.com"))
				.version("1.0")
				.build();
	}
}

五.更改application.yml里的路径匹配策略

由于swagger支持的路径匹配方式是ant-path-matcher策略，spring boot版本太高默认是path-pattern-parser，所以这里使用spring boot高版本的小伙伴需要更改一下，否则高版本运行项目时会报空指针。

感兴趣的小伙伴也可以研究一下path-pattern-parser和ant-path-matcher的区别

Spring5新宠：PathPattern，AntPathMatcher：那我走？_方向盘(YourBatman)的博客-CSDN博客

六.写测试案例

常用的注解都在这些测试案例里，还有很多其他注解可以自行百度

先写一个Controller类

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import top.xiewenwen.common.vo.JsonResult;
import top.xiewenwen.common.vo.User;

/**
 * 
 * @author AWen
 * @date 2022年11月10日 
 */
@RestController
@RequestMapping("/swagger")
@Api(value = "MES接口")
public class SwaggerController {
 
    @GetMapping("/get/{id}")
    @ApiOperation(value = "根据用户唯一标识获取用户信息")
    public JsonResult getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {
            // 模拟数据库中根据id获取User信息
            User user = new User(id, "zhuangzi", "123456");
            return new JsonResult(user);
    }
 
}

写User类

package top.xiewenwen.common.vo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * 
 * @author AWen
 * @date 2022年11月10日 
 */
 
@ApiModel(value = "用户实体类")
public class User {
    @ApiModelProperty(value = "用户唯一标识",example = "1")
    private Long id;
    @ApiModelProperty(value = "用户名",example = "1")
    private String username;
    @ApiModelProperty(value = "用户密码",example = "1")
    private String userpwd;
 
    public User(Long id, String username, String userpwd) {
        this.id = id;
        this.username = username;
        this.userpwd = userpwd;
    }

	public Long getId() {
		return id;
	}

	public void setId(Long id) {
		this.id = id;
	}

	public String getUsername() {
		return username;
	}

	public void setUsername(String username) {
		this.username = username;
	}

	public String getUserpwd() {
		return userpwd;
	}

	public void setUserpwd(String userpwd) {
		this.userpwd = userpwd;
	}
    
    
}

写JsonResult类

package top.xiewenwen.common.vo;

import java.io.Serializable;

public class JsonResult implements Serializable{
	private static final long serialVersionUID = -1;
	/**状态码*/
	private String result="true";//true表示SUCCESS,false表示ERROR
	/**状态信息*/
	private String message="ok";
	/**正确数据*/
	private Object data;
	public JsonResult() {}
	public JsonResult(String message){
		this.message=message;
	}
	/**一般查询时调用，封装查询结果*/
	public JsonResult(Object data) {
		if(data.toString().equals("[]")) {
			this.result="false";
			this.message="未获取到数据";
		}
		this.data=data;
	}
	/**出现异常时时调用*/
	public JsonResult(Throwable t){
		this.result="false";
		this.message=t.getMessage();
	}
	public String getResult() {
		return result;
	}
	public void setResult(String result) {
		this.result = result;
	}
	public String getMessage() {
		return message;
	}
	public void setMessage(String message) {
		this.message = message;
	}
	public Object getData() {
		return data;
	}
	public void setData(Object data) {
		this.data = data;
	}
}

七.实现效果

运行项目，访问静态文件的index.html

这里打开是UI界面默认的接口路径，所以要换成我们自己的接口路径，在上面收索自己的接口路径，不一样的版本，接口路径不一样，我的是http://localhost:8085/v2/api-docs ，使用swagger3版本的小伙伴路径有可能是http://localhost:8085/v3/api-docs ，不清楚自己版本接口的小伙伴，可以自行百度一下，然后填写自己的swagger接口,点击旁边Explore按钮，就能看见swagger的接口文档，下面那两个是我另外加的

由于每次进入界面需要收索很麻烦，可以找到dist文件里的swagger-initializer.js文件，把默认路径改成自己的路径就行了，这样打开index.html就是自己的文档了，感觉界面不好看的也可以根据自己喜欢更爱css文件，或者用第三方页面调用接口是一样的，这篇文章到这结束，希望对您有帮助。