什么是 Swagger
Swagger 是一个 Restful 风格接口的文档在线自动生成和测试的框架
官网：http://swagger.io
官方描述：The World’s Most Popular Framework for APIs.
springboot 集成 swagger -ui
1、pom.xml 中添加依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>2、在 Application 同级目录新建 SwaggerController 文件
package com.zuolh.lab;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;
//swagger2的配置文件，在项目的启动类的同级文件建立
@Configuration
@EnableSwagger2
//是否开启swagger，正式环境一般是需要关闭的（避免不必要的漏洞暴露！），可根据springboot的多环境配置进行设置
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
public class SwaggerController {
// swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.pathMapping("/")
.select()
// 为当前包路径
.apis(RequestHandlerSelectors.basePackage("com.zuolh.lab"))
.paths(PathSelectors.any())
.build();
}
// 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 页面标题
.title("zuolh的接口文档")
// 创建人信息
.contact("zuolh")
// 版本号
.version("1.0")
// 描述
.description("更多请关注：https://www.zuolh.com/")
.termsOfServiceUrl("https://www.zuolh.com/")
.version("1.0")
.build();
}
}3、在 controller 上添加注解，自动生成 API
package com.zuolh.lab;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import javax.servlet.http.Cookie;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.HashMap;
import java.util.Objects;
import java.util.Map;
/**
* <p/>
*
* @author zuolihong
* @version 1.0
* @className MyGetMethod
* @date 2021/4/30 14:27
*/
@RestController
@RequestMapping("/zuo")
@Api(description = "get请求")
public class MyGetMethod {
/**
* 调用接口将cookie信息加到浏览器的cookie中去
* @param response
* @return
*/
@ApiOperation(value="向浏览器添加cookies信息")
@GetMapping("/addCookies")
public String addCookies(HttpServletResponse response){
Cookie cookie = new Cookie("login","true1");
response.addCookie(cookie);
return "返回cookies信息成功";
}
/**
* 要求客户端携带cookies访问
*/
@RequestMapping(value = "/get/with/cookies",method = RequestMethod.GET)
@ApiOperation(value="判断访问是否带入cookie信息")
public String getWithCookies(HttpServletRequest request){
Cookie[] cookies = request.getCookies();
if(Objects.isNull(cookies)){
return "必须携带cookies信息111";
}
for(Cookie cookie:cookies){
System.out.println("----------------"+cookie.getName()+" "+cookie.getValue());
if (cookie.getName().equals("login1") && cookie.getValue().equals("false")){
return "访问成功";
}
}
return "必须携带cookies信息2222";
}
/**
* 第一种：需要访问携带参数的get请求，参数格式是param=p1&¶m1=p2
*
*/
@GetMapping("/get/with/param")
@ApiOperation(value="访问带有参数")
@ApiImplicitParam(paramType = "query",name = "a",dataType = "String",required = true,value = "输入的服饰类型",defaultValue = "裤子")
public String getWithParam(@RequestParam String a){
return putList(a);
}
public String putList(String a){
Map<String, String> list = new HashMap<>();
list.put("鞋子","100");
list.put("裤子","500dddddddddd");
return list.get(a);
}
/**
* 第二种：需要访问携带参数的get请求，参数格式是ip:port/get/cookies/param1/param2格式
*/
@ApiOperation("访问带的参数格式与上一个方法不同")
@RequestMapping(value = "/get/with/param/{a}",method = RequestMethod.GET)
public String getWithParam1(@PathVariable String a){
Map<String, String> list = new HashMap<>();
list.put("鞋子","100");
list.put("裤子","500");
return list.get(a);
}
}注解含义：
@Api：用在请求的类上，表示对类的说明
tags="说明该类的作用，可以在UI界面上看到的注解"
value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
@ApiOperation：用在请求的方法上，说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性
4、启动后效果图：
启动成功后访问：http://localhost:8889/swagger-ui.html
