背景介绍

什么是Swagger2

常用注解

SpringBoot整合Swagger2

生产环境下屏蔽Swagger2

修改Swagger2配置类

修改application.yml

使用maven package打包测试

运行测试

背景介绍

在团队开发中，一个好的 API 文档不但可以减少大量的沟通成本，还可以帮助一位新人快速上手业务。传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节，并在程序员之间代代相传。这种做法存在以下几个问题：
1）API 接口众多，细节复杂，需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等，想要高质量的完成这份文档需要耗费大量的精力；
2）难以维护。随着需求的变更和项目的优化、推进，接口的细节在不断地演变，接口描述文档也需要同步修订，可是文档和代码处于两个不同的媒介，除非有严格的管理机制，否则很容易出现文档、接口不一致的情况；

Swagger2 的出现就是为了从根本上解决上述问题。它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务：
接口文档在线自动生成，文档随接口变动实时更新，节省维护成本；
支持在线接口测试，不依赖第三方工具；

什么是Swagger2

Swagger2 是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务，现在我们使用spring boot 整合它。作用：
接口的文档在线自动生成；
功能测试；

常用注解

注解	描述
@Api	将类标记为 Swagger 资源。
@ApiImplicitParam	表示 API 操作中的单个参数。
@ApiImplicitParams	允许多个 ApiImplicitParam 对象列表的包装器。
@ApiModel	提供有关 Swagger 模型的其他信息。
@ApiModelProperty	添加和操作模型属性的数据。
@ApiOperation	描述针对特定路径的操作或通常是 HTTP 方法。
@ApiParam	为操作参数添加额外的元数据。
@ApiResponse	描述操作的可能响应。
@ApiResponses	允许多个 ApiResponse 对象列表的包装器。
@Authorization	声明要在资源或操作上使用的授权方案。
@AuthorizationScope	描述 OAuth2 授权范围。

SpringBoot整合Swagger2

导入依赖

   io.springfox   springfox-swagger2   2.9.2               swagger-models       io.swagger           com.github.xiaoymin   swagger-bootstrap-ui   1.8.5   io.swagger   swagger-models   1.5.22

创建Swagger配置类

@Configuration//开启Swagger2@EnableSwagger2//配置生产环境下不可用  dev(开发)、test(测试)、prod(生产)@Profile({"dev","test"})public class Swagger2Configuration extends WebMvcConfigurationSupport {   //api接口包扫描路径   public static final String       SWAGGER_SCAN_BASE_PACKAGE = "com.lky.swagger2pro.controller";   //指定当前Swagger API文档版本   public static final String VERSION = "1.0.0";   /**   * 创建API应用   * apiInfo() 增加API相关信息   * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，   * 本例采用指定扫描的包路径来定义指定要建立API的目录。   * @return   */   @Bean   public Docket createRestApi() {     return new Docket(DocumentationType.SWAGGER_2)         // 接口文档的基本信息         .apiInfo(apiInfo())         .select()         // 方法需要有ApiOperation注解才能生存接口文档         //.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))         .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))         // 路径使用any风格         .paths(PathSelectors.any())         .build();   }   /**   * 创建该API的基本信息（这些基本信息会展现在文档页面中）   * 访问地址：http://项目实际地址/doc.html   * @return   */   private ApiInfo apiInfo() {     return new ApiInfoBuilder()         .title("SpringBoot中使用Swagger2构建RestFul APIs")         .description("测试系统")         //.termsOfServiceUrl("http://www.**.com")         .version(VERSION)         .build();   }   @Override   protected void addResourceHandlers(ResourceHandlerRegistry registry) {     registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");     registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");   }}

1) 完成以上配置之后，通过mybatis-generator生成model和mapper； 2) 创建IBookService及BookServiceImpl实现类； 3) 创建BookController

综合案例

@Api

@Api注解用在类上，说明该类的作用。可以标记一个Controller类做为swagger文档资源。

属性	说明
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
produces	返回的格式类型例如：”application/json, application/xml”
consumes	接收请求参数的类型例如：”application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置

案例演示

@RestController@Api(value = "书本管理",tags = {"书本管理"}) //tags可以代替value属性@RequestMapping("/book")public class BookController {   ...}

@ApiOperation

@ApiOperation注解用在方法上，说明方法的作用，每一个url资源的定义。

属性	说明
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
produces	返回的格式类型例如：”application/json, application/xml”
consumes	接收请求参数的类型例如：”application/json, application/xml”
hidden	是否在文档中显示
notes	注释说明
response	返回的对象
responseContainer	这些对象是有效的 “List”, “Set” />
responseReference	指定对响应类型的引用。指定的引用可以是本地的，也可以是远程的*将按原样使用，并覆盖任何指定的response()类
responseHeaders	响应旁边提供的可能标题列表
httpMethod	“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code	http的状态码默认 200

案例演示

@ApiOperation(value = "查询所有书本信息", notes = "查询返回所有书本信息集合",       produces = "application/json")@GetMapping(value="/queryAll")public JsonResponseBody<List> queryAll(){   try {     return bookService.queryAll();   } catch (Exception e) {     e.printStackTrace();     return new JsonResponseBody(500,e.getMessage());   }}

@ApiImplicitParam

@ApilmplicitParam 注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入；

属性	说明
paramType	参数放在哪个地方
name	参数名称
value	参数代表的含义
dataType	参数类型
dataTypeClass	参数类型
required	是否必要
defaultValue	参数的默认值

paramType

类型	作用
path	以地址的形式提交数据，用于restful接口。请求参数采用@PathVariable获取
query	直接跟参数完成自动映射赋值。请求参数可采用@RequestParam获取
body	以流的形式提交，仅支持POST。请求参数采用@RequestBody获取
header	参数在request headers里边提交。请求参数采用@RequestHeader获取
form	以form表单的形式提交，仅支持POST。

案例演示

@ApiOperation(value="查询单个书本信息",notes = "查询单个书本信息")@ApiImplicitParam(value="书本ID",name="bookid",required = true,dataType = "String",defaultValue = "8f46b5018a6811e9a9c528d24413c293" )@GetMapping("/querySingleBook")public Book querySingleBook(String bookid){   JsonResponseBody json = bookService.selectByPrimaryKey(bookid);   return json.getData();}

@ApiImplicitParams

@ApilmplicitParams 如果有多个参数，则需要使用多个 @ApilmplicitParam 注解来描述，多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中；

案例演示

@ApiOperation(value = "新增书本信息", notes = "新增书本信息"       ,produces = "application/json",consumes = "application/json")@ApiImplicitParams({       @ApiImplicitParam(name="bookname",value="书本名称",required = true,dataType = "String"),       @ApiImplicitParam(name="price",value="书本价格",required = true,dataType = "Double"),       @ApiImplicitParam(name="booktype",value="书本类型",required = true,dataType = "String")})@PostMapping("/addBook")public JsonResponseBodyhttps://www.jianshu.com/p/fa3230ffb27c
  一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!
  一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!
  一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!
  修改Swagger2配置类
   添加@Profile注解，指明在何种环境下可以使用Swagger2，一般情况下只有在开发(dev)和测试(test)环境下才可以使用Swagger2；而在生产(dev)环境下不能使用Swagger2。
 
 @Configuration//开启Swagger2@EnableSwagger2//配置生产环境下不可用  dev(开发)、test(测试)、prod(生产)@Profile({"dev","test"})public class Swagger2Configuration extends WebMvcConfigurationSupport {        ...    @Override    protected void addResourceHandlers(ResourceHandlerRegistry registry) {        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");    }}
修改application.yml
修改application.yml文件，配置项目系统的运行环境（dev/test/prod）
spring:  #配置swagger2生产和测试环境不可用  profiles:    active: prod
使用maven package打包测试
运行测试
打开CMD，跳转到target目录，输入命令：java -jar .\xxx.jar --spring.profiles.active=prod。可以直接打开jar包修改application.yml配置文件中spring.profiles.active属性切换运行环境，具体请参考以下配置：
开发环境：dev；
生产环境：prod；
测试环境：test；
以上就是今天有关于Swagger2的介绍和使用！

第二章：Swagger2

背景介绍

什么是Swagger2

常用注解

SpringBoot整合Swagger2

导入依赖

创建Swagger配置类

综合案例

@Api

@ApiOperation

@ApiImplicitParam

@ApiImplicitParams

修改Swagger2配置类

修改application.yml

使用maven package打包测试

运行测试

以上就是今天有关于Swagger2的介绍和使用！

`最新关注`

`热文推荐`

`[架构之路-243]：目标系统 – 纵向分层 – 架构是表面轮廓、内部骨架、未来蓝图，企业组织架构、信息系统架构、软件架构、应用程序就架构`

`黄东旭：“向量数据库”还是“向量搜索插件 + SQL 数据库”？丨我对 2024 年数据库发展趋势的思考`

`Kafka系列之：Kafka集群同时设置基于时间和日志大小两种方式保存Topic的数据`

`数字之美：探索人工智能绘画的奇妙世界`

`万物云原生下的服务进化`

`【ArcGIS Pro微课1000例】0052：基于SQL Server创建企业级地理数据库案例`

第二章：Swagger2

背景介绍

什么是Swagger2

常用注解

SpringBoot整合Swagger2

导入依赖

创建Swagger配置类

综合案例

@Api

@ApiOperation

@ApiImplicitParam

@ApiImplicitParams

修改Swagger2配置类

修改application.yml

使用maven package打包测试

运行测试

以上就是今天有关于Swagger2的介绍和使用！

相关文章

最新关注

热文推荐

`相关文章`

`最新关注`

`热文推荐`