在springboot中搭建swagger文档

其他 2021-01-24 11:43:50 阅读次数: 0

文章目录

前提

  • 学过springboot

1.导包

	<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>

2.配置config类，访问ui页面

package cn.liuhao.config;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
// 开启swagger自动配置
@EnableSwagger2
public class SwaggerConfig {
    
    

}

配置这个类，通过springboot启动类启动后，访问http://localhost:8080/swagger-ui.html
访问成功则会出现以下页面表示成功
在这里插入图片描述

3.配置api文档信息

package cn.liuhao.config;

import java.util.ArrayList;

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

import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2 // 开启swagger
public class SwaggerConfig {
    
    

	@Bean
	public Docket docket() {
    
    

		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
	}

	/**
	 * api的基本信息
	 * 
	 * @return
	 */
	public ApiInfo apiInfo() {
    
    

		String title = "标题";
		String description = "描述";
		String version = "版本";
		String termsOfServiceUrl = "所属组织公共网址";

		String username = "创建者名称";
		String userUrl = "创建者主页";
		String userEmail = "创建者邮箱";

		String licenseName = "许可证名称";
		String licenseUrl = "许可证网络地址";

		return new ApiInfo(title, description, version, termsOfServiceUrl, new Contact(username, userUrl, userEmail),
				licenseName, licenseUrl, new ArrayList<VendorExtension>());
	}
}

4.配置扫描指定路径的接口

4.1扫描指定包里的接口

swagger可以指定扫描项目包路径下的接口

修改swaggerConfig类

@Bean
	public Docket docket() {
    
    

		Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
		// 在指定包路径下扫描接口
		docket.select().apis(RequestHandlerSelectors.basePackage("cn.liuhao.controller")).build();

		return docket;
	}

4.2通过扫描指定注解获取接口

通过扫描指定类注解，获取所在类下的接口方法

	@Bean
	public Docket docket() {
    
    

		Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
		// 通过扫描指定注解，获取所在类下的接口方法
		docket.select().apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)).build();

		return docket;
	}

// 通过扫描指定方法注解，获取当前方法接口

	@Bean
	public Docket docket() {
    
    

		Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
		// 通过扫描指定方法注解，获取当前方法接口
		docket.select().apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class)).build();

		return docket;
	}

4.3扫描所有接口，或者不扫描

扫描所有接口

	@Bean
	public Docket docket() {
    
    

		Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
		
		docket.select().apis(RequestHandlerSelectors.any()).build();

		return docket;
	}

不扫描任何接口

	@Bean
	public Docket docket() {
    
    

		Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
		
		docket.select().apis(RequestHandlerSelectors.none()).build();

		return docket;
	}

4.4 扫描指定包下的所有接口，并且使用过滤处指定类型接口外的其他接口

	@Bean
	public Docket docket() {
    
    

		Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
		// 扫描指定包下的所有接口，并且使用过滤处指定类型接口外的其他接口
		docket.select().apis(RequestHandlerSelectors.basePackage("cn.liuhao.controller"))
				.paths(PathSelectors.ant("/user")).build();

		return docket;
	}

在这里插入图片描述

5.配置接口忽略指定类型参数

例如忽略服务器自带的对象，request，response，session，application等

	@Bean
	public Docket docket() {
    
    

		Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());

		// 忽略指定类型的接口参数
		docket.ignoredParameterTypes(HttpServletRequest.class, HttpServletResponse.class);

		return docket;
	}

6.通过enable(bool)方法指定是否在展示页面

	@Bean
	public Docket docket() {
    
    

		Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());

		// enable 方法接受一个boolean值，true代表展示页面，false代表不展示
		docket.enable(true);

		return docket;
	}

不展示就会出现如下页面
在这里插入图片描述

7.为api配置分组

有多个分组就写多个bean实例

	@Bean
	public Docket docketUser() {
    
    

		Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());

		docket.select().apis(RequestHandlerSelectors.basePackage("cn.liuhao.controller"))
				.paths(PathSelectors.ant("/user/**")).build();
		docket.groupName("用户接口");

		return docket;
	}

	@Bean
	public Docket docketHello() {
    
    

		Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());

		docket.select().apis(RequestHandlerSelectors.basePackage("cn.liuhao.controller"))
				.paths(PathSelectors.ant("/hello/**")).build();
		docket.groupName("hello接口");

		return docket;
	}

在这里插入图片描述

8.配置实体信息

实体类

注解 作用
@ApiModel 用来描述一个类
@ApiModelProperty 用来描述实体类的属性 
package swagger03.web.pojo;

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

@ApiModel("用户实体")
public class User {
    
    

	@ApiModelProperty("ID")
	private int id;

	@ApiModelProperty("姓名")
	private String name;

	@ApiModelProperty("年龄")
	private String age;

	public int getId() {
    
    
		return id;
	}

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

	public String getName() {
    
    
		return name;
	}

	public void setName(String name) {
    
    
		this.name = name;
	}

	public String getAge() {
    
    
		return age;
	}

	public void setAge(String age) {
    
    
		this.age = age;
	}

	public User(int id, String name, String age) {
    
    
		super();
		this.id = id;
		this.name = name;
		this.age = age;
	}

	public User() {
    
    
		// TODO Auto-generated constructor stub
	}
}

controller接口

注解 作用
@RequestBody 如果接口参数是一个实体类，虽然我们描述了实体类，但是作为接口参数，swagger并不会描述，我们需要手动添加 @RequestBody 来描述 
package swagger03.web.controller;

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

import swagger03.web.pojo.User;

@RestController
@RequestMapping("user")
public class UserController {
    
    
	
	// 注意，方法返回的类型一定要是我们描述好的实体类类型，否则swagger不能是被
	// 返回user就必须用user类型当返回值，不能使用object
	@GetMapping("getUser")
	public User getUser(@RequestBody User u) {
    
    

		return u;
	}

}

9.配置全局参数（类似token这种参数）

代码

package swagger03.config;

import java.util.ArrayList;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    

	public Docket docket() {
    
    

		Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(docketInfo());
		// 在指定包路径下扫描接口
		docket.select().apis(RequestHandlerSelectors.basePackage("swagger03.web.controller")).build();
		// 创建全局参数类型可以是请求头参数（header），url参数（query）
		Parameter token = new ParameterBuilder().name("token").description("用户令牌").parameterType("header")
				.required(true).build();
		// 添加参数
		ArrayList<Parameter> paramers = new ArrayList<Parameter>();
		paramers.add(token);
		// 将参数集合放进docket对象
		docket.globalOperationParameters(paramers);

		return docket;
	}

	private ApiInfo docketInfo() {
    
    

		return null;
	}
}

10.接口以及参数配置

注解

注解名 含义
@Api 用来描述接口类的作用
@ApiOperation 用来描述一个方法的作用
@ApiImplicitParams 描述多个接口参数
@ApiImplicitParam 描写单个接口参数的作用 
package swagger03.web.controller;

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

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import swagger03.web.pojo.User;

@Api(tags = "用户接口", description = "一些用户相关的参数")
@RestController
@RequestMapping("user")
public class UserController {
    
    

	@ApiOperation("通过用户名和ID来获取用户对象")
	@ApiImplicitParams({
    
     @ApiImplicitParam(name = "id", dataType = "int", defaultValue = "0", required = true),
			@ApiImplicitParam(name = "name", dataType = "String", defaultValue = "张三", required = true) })
	@GetMapping
	public User getUserById(int id, String name) {
    
    

		return new User();
	}

}

在这里插入图片描述

11.NumberFormatException异常解决办法

参考

参考博客

推荐解决办法

	<!--问题出现在1.5.20版本，1.5.22版本解决了这个问题，所以我们直接覆盖-->
	<dependency>
			<groupId>io.swagger</groupId>
			<artifactId>swagger-annotations</artifactId>
			<version>1.5.22</version>
		</dependency>
		<dependency>
			<groupId>io.swagger</groupId>
			<artifactId>swagger-models</artifactId>
			<version>1.5.22</version>
		</dependency>

猜你喜欢

转载自blog.csdn.net/qq_42418169/article/details/109169059
今日推荐
Linus “吃狗粮”最积极！
开源日报 | Winamp播放器即将开源；生成式AI之战升级第二轮；Linus“吃狗粮”最积极；AI进入泡沫前期；吴泳铭为阿里云带来了什么？
NetBSD 禁止提交由 AI 生成的代码
Apache Doris 2.0.10 版本正式发布！
开源日报 | 大模型开战；大模型独角兽被曝卖身；周鸿祎建议谷歌开源所有产品；最大开源AI社区提供1000万美元共享GPU
开源日报 | Chrome内置Gemini的意义不在于Gemini；中国AI追随之路的五大误区；ECharts创始人“下海”养鱼；谷歌I/O开发者大会什么都有，只是没有惊喜
微软回应中国区AI团队“打包赴美”传闻
周排行
SVN服务端安装在阿里云
实战 | 相机标定
webpack核心概念
note20——》只要肯低头吃苦，人生就会有救
PAT甲级 1062 Talent and Virtue （25 分）排序
NG Toolset开发笔记--5GNR Resource Grid（26）
如何对待上司
oracle命令
第9章 STL迭代器
logstash使用es映射模板
每日归档
更多
2024-05-20(36)
2024-05-19(0)
2024-05-18(4)
2024-05-17(34)
2024-05-16(6)
2024-05-15(24)
2024-05-14(0)
2024-05-13(18)
2024-05-12(0)
2024-05-11(38)

代码天地 © 2018 codetd.com

境外服务器   最新电视剧2022