SpringBoot整合Swagger2入门示例

最新推荐文章于 2024-10-05 18:10:34 发布

if_icanfly

最新推荐文章于 2024-10-05 18:10:34 发布

阅读量312

点赞数

分类专栏： SpringBoot 文章标签： spring boot

本文链接：https://blog.csdn.net/if_icanfly/article/details/107842296

版权

SpringBoot 专栏收录该内容

8 篇文章 0 订阅

订阅专栏

1.新建一个springboot项目,勾选spring web

2.添加swagger的依赖

		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>swagger-bootstrap-ui</artifactId>
			<version>1.9.6</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>cy>

3.配置swagger,新建config的包,然后新建一个swagger的配置文件.内容如下

package com.nlx.config;

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

import com.google.common.base.Predicates;

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

@Configuration
@EnableSwagger2 // Swagger的开关，表示已经启用Swagger
public class SwaggerConfig {
    @Bean
    public Docket api() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select() // 选择哪些路径和api会生成document
                .apis(RequestHandlerSelectors.any())// 对所有api进行监控
                //.apis(RequestHandlerSelectors.basePackage("com.hanstrovsky.controller"))// 选择监控的package
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 只监控有ApiOperation注解的接口
                //不显示错误的接口地址
                .paths(Predicates.not(PathSelectors.regex("/error.*")))//错误路径不监控
                .paths(PathSelectors.regex("/.*"))// 对根下所有路径进行监控
                .build();
        return docket;
    }

    private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("api文档的标题或者名称")
				.description("这里是关于这个api文档的简单描述")
				.termsOfServiceUrl("http://localhost:8080/")//访问地址
				.version("1.0.0")// 版本号
				.build();
	}
}

项目结构如下

启动项目.(默认端口访问) http://localhost:8080/doc.html

由于我们还没有些接口,所左边的列表只有有限的几个信息

4.在接口上使用swagger注解

新建controller的包,然后再controller下新建模块的包,

上图是新建了三个用于测试的模块,每个模块2个controller,每个controller里面包含2个方法.

package com.nlx.controller.admin;

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

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

@RestController
// swagger的注解 
@Api(value = "后台管理", tags = { "后台管理-模块一" })
@RequestMapping("/admin1")
public class AdminController {

    //swagger的注解 
	@ApiOperation(value = "后台管理模块一新增")
	@PostMapping("/add")
	public String add() {
		return "success";
	}
    //swagger的注解 
	@ApiOperation(value = "后台管理模块一查询")
	@GetMapping("/get")
	public String select() {
		return "success";
	}
}

重启项目

6个controller对应上图6个模块,每个模块包含2个方法.

5.按包进行分组

通常情况下一个项目可能有很多的接口成百上千,全部列出来会很难找,于是我们可以按照一定的规则进行划分

在swaggerconfig配置文件里面新建分组

package com.nlx.config;

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

import com.google.common.base.Predicates;

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

@Configuration
@EnableSwagger2 // Swagger的开关，表示已经启用Swagger
public class SwaggerConfig {
    @Bean
    public Docket api() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select() // 选择哪些路径和api会生成document
                .apis(RequestHandlerSelectors.any())// 对所有api进行监控
                //.apis(RequestHandlerSelectors.basePackage("com.hanstrovsky.controller"))// 选择监控的package
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 只监控有ApiOperation注解的接口
                //不显示错误的接口地址
                .paths(Predicates.not(PathSelectors.regex("/error.*")))//错误路径不监控
                .paths(PathSelectors.regex("/.*"))// 对根下所有路径进行监控
                .build();
        return docket;
    }

    private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("api文档的标题或者名称")
				.description("这里是关于这个api文档的简单描述")
				.termsOfServiceUrl("http://localhost:8080/")//访问地址
				.version("1.0.0")// 版本号
				.build();
	}
    
/**#######################################以下内容为新增###########################################*/
    @Bean(value = "userApi")
	public Docket userApi() {
		Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
				// 分组名称
				.groupName("用户管理模块").select()
				// 这里指定Controller扫描包路径
				.apis(RequestHandlerSelectors.basePackage("com.nlx.controller.user"))
				.paths(PathSelectors.any()).build();
		return docket;
	}
    @Bean(value = "adminApi")
   	public Docket adminApi() {
   		Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
   				// 分组名称
   				.groupName("后台管理模块").select()
   				// 这里指定Controller扫描包路径
   				.apis(RequestHandlerSelectors.basePackage("com.nlx.controller.admin"))
   				.paths(PathSelectors.any()).build();
   		return docket;
   	}
    @Bean(value = "menberApi")
   	public Docket menberApi() {
   		Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
   				// 分组名称
   				.groupName("会员管理模块").select()
   				// 这里指定Controller扫描包路径
   				.apis(RequestHandlerSelectors.basePackage("com.nlx.controller.menber"))
   				.paths(PathSelectors.any()).build();
   		return docket;
   	}
}

添加了三个@bean,路径分别指向controller下的三个模块的包
注意:groupName里面不能包含特殊字符,[]这样的在选择分组的时候会报错

重启项目:

选择其中一个模块:

6.增强排序功能，添加个性化配置管理功能,可开启个性化配置

在原EnableSwagger2注解上增加@EnableSwaggerBootstrapUi注解

package com.nlx.config;

import org.springframework.context.annotation.Configuration;
import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2 // Swagger的开关，表示已经启用Swagger
@EnableSwaggerBootstrapUI //swaggerUI增强注解
public class SwaggerConfig {
   
}

添加注解实现排序

@ApiOperationSupport(order = 2, author = "anonym")
order为排序字段

关于swagger注解的使用,swagger常用注解