Swagger简单使用之从入门到精通

Swagger简介

1、Swagger 是一个规范和完整的框架，用于生成、描述、调用。

2、号称世界上最流行的Api框架。

3、RestFul Api文档在线自动生成工具（Api文档与Api定义同步更新）

4、支持多种语言。

官网：API Documentation & Design Tools for Teams | Swagger

简单使用Swagger

在项目中使用Swagger，需要SpringBox（swagger2、swagger-ui）。

1、SpringBoot集成Swagger

1.1、新建一个SpringBoot的Web项目

1.2、导入相关Maven依赖

注：需要注意SpringBoot与Swagger版本，不然会报错。若springboot项目的版本低，相应的swagger版本不能太高，反之亦然。（这里使用SpringBoot版本为：2.4.1、Swagger版本为2.9.2）

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency><!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>

1.3、配置Swagger

package com.yang.swagger.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.GetMapping;
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;import java.util.ArrayList;//配置进SpringBoot中
@Configuration
//开启Swagger2
@EnableSwagger2
public class SwaggerConfig {//配置Swagger的Docket的Bean实例@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2)//.enable(true/false):// 是否启用Swagger.apiInfo(apiInfo()).select()//RequestHandlerSelectors：配置要扫描接口的方式//basePackage:指定需要扫描的包(推荐使用)//any:扫描全部//none：都不扫描//withClassAnnotation:扫描类上的注解,RequestHandlerSelectors.withClassAnnotation(RestController.class)//withMethodAnnotation：扫描方法上的注解,RequestHandlerSelectors.withMethodAnnotation(GetMapping.class).apis(RequestHandlerSelectors.basePackage("com.yang.swagger.controller"))//PathSelectors：过滤//ant("/Yang/**"): 只过滤出'Yang'下的所有接口//any():过滤全部.paths(PathSelectors.any()).build();}//配置Swagger信息的apiInfoprivate ApiInfo apiInfo(){//作者信息Contact contact = new Contact("Yang", "https://blog.csdn.net/qq_42696004?spm=1000.2115.3001.5343", "1102046099@qq.com");return new ApiInfo("杨的SwaggerAPI文档",    //标题"不行不想努力",    //个人简述"1.0",               //版本号"https://blog.csdn.net/qq_42696004?spm=1000.2115.3001.5343",  //组织地址contact,                     //作者信息"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList());}}

1.4、测试运行（访问http://localhost:8080/swagger-ui.html即可）

（默认显示）

（配置后显示）

配置Api文档的分组

接口注释

@Api : 用在类上，说明该类的主要作用。

@ApiOperation：用在方法上，给API增加方法说明。

@ApiImplicitParams : 用在方法上，包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiModel：用在返回对象类上，描述一个Model的信息。

总结

我们可以通过Swagger给一些比较难理解的属性或接口，增加注释消息。接口文档实时更新。可以在线测试。

出于安全考虑，且能节省运行的内存，若项目正式发布，建议关闭Swagger！！！！