时间戳

首页 > 技术文章 > SpringBoot集成swagger API框架

SpringBoot集成swagger API框架

zhangquan-yw 2020-12-28 17:59 原文

SpringBoot集成swagger API框架

制作人：全心全意

SpringBoot集成swagger API框架

　　前后端分离
　　　　接口名、地址、参数、返回值、请求方式、请求示例等
　　　　　　接口名：用户登录
　　　　　　地址：127.0.0.1:8080/login/login.action
　　　　　　参数：{username:'admin',passwd:'123456'}
　　　　　　返回值：{code:1,msg:'登陆成功'}
　　　　　　请求方式：get
　　　　　　请示示例：

 

swagger的作用就是自动生成接口文档供前端开发人员查看

 

引入依赖

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

　　

配置配置文件

swagger:
  enabled: true		#启用swagger
  base-package: com.zq.main.controller	#扫描位置

　　

controller类的标注

package com.zq.main.controller;

import java.util.ArrayList;
import java.util.Map;

import javax.servlet.http.HttpServletRequest;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

@Controller
@Api(consumes = "模板测试", tags = "模板测试")  //API类的标注
public class MyThymeleafController {
	@RequestMapping("/myThymeleaf")
	@ApiOperation(consumes = "模板1", notes = "模板2", value = "hello,swagger")	//API接口的标注
	public String myThymeleaf(Map<String, Object> result) {
		ArrayList<String> str1 = new ArrayList<>();
		str1.add("123");
		str1.add("456");
		result.put("str1", str1);
		return "myThymeleaf";
	}
}

　　

启动类

package com.zq.main;

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

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2 // 开启swagger
public class App {
	public static void main(String[] args) {
		SpringApplication.run(App.class, args);
	}
}

　　

访问地址：http://127.0.0.1:8012/zq/swagger-ui.html

 

相关注解解释

　　@Api
　　　　tags：接口类标签名

　　@ApiOperation
　　　　value：接口方法标签名
　　　　notes：接口描述


　　@RequestBody：在参数提交时使用，可以将提交的json格式化为字符串,使用此注解，swagger会提供请求示例，建议使用post请求，自测试使用get报错
　　　　public String test(@RequestBody User user){}

　　@ApiImplicitParams：@ApiImplicitParam的包装
　　@ApiImplicitParam：设置参数
　　　　name：字段名称
　　　　value：字段描述提示
　　　　required：参数是否必填
　　　　paramType：设置参数类型（中文）
　　　　dataType：设置数据类型（英文）

　　@RequestParam：在示例中可有可无，作为为解决表单提交的参数和字段不对应的问题

 

测试示例：

@ApiOperation(consumes = "测试", notes = "测试用", value = "hello,swagger")
@ApiImplicitParams({
		@ApiImplicitParam(name = "name", value = "用户姓名", required = true, paramType = "字符串", dataType = "String") })
@DeleteMapping("/hello1")
public String HelloController1(@RequestParam("name") String name) {
	System.out.println(name);
	return "456";
}

　　

 

更换UI（swagger默认的ui效果一般）

依赖包的配置

<dependency>
	<groupId>com.spring4all</groupId>
	<artifactId>swagger-spring-boot-starter</artifactId>
	<version>1.9.0.RELEASE</version>
	<exclusions>
		<exclusion> <!-- 排除默认的ui -->
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
		</exclusion>
	</exclusions>
</dependency>

<!-- 引入新的UI -->
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>swagger-bootstrap-ui</artifactId>
	<version>1.9.6</version>
</dependency>

　　

新的UI地址：http://127.0.0.1:8012/zq/doc.html

 

重写配置类：写此配置类可以不配置application配置文件

package com.zq.main;

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.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		//此处使用了EnableSwagger2，启动类中可省略
public class Swagger2AutoConfiguration {

	@Bean
	public Docket swaggerSpringMvcPlugin() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
				.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
				.build();

	}

	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().description("描述")
				.contact(new Contact("全心全意", "http://www.baidu.com", "1006319959@qq.com"))
				.version("3.3").license("北京").build();
	}

}

　　

推荐阅读