Swagger强大的API文档工具

1.Swagger是什么？
Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTfu风格的web服务。
简单点来讲就是，swagger是一款可以根据restful风格生成的接口开发文档，并且支持做测试的一款中间软件。官网地址 https://swagger.io/
Swagger是一个流行的API开发框架，Swagger允许用户使用Swagger编辑器描述OAS 3.0 API（OpenAPI Specification，OAS），并使用Swagger UI可视化并自动生成OAS 3.0中定义的API文档。
Swagger 对整个API的开发周期都提供了相应的解决方案，是一个规范和完整的框架。包括API设计、API开发、API文档、API测试、API治理等，Swagger几乎支持所有语言。
1.1 swagger 和springfox的区别?
Swagger UI 允许用户使用Swagger编辑器描述OAS 3.0 API，并使用Swagger UI可视化并自动生成OAS 3.0中定义的API文档。
Springfox 用Spring构建自动的 JSON API文档的工具。
Swagger 是一种规范。
springfox-swagger 是基于 Spring 生态系统的该规范的实现。
springfox-swagger-ui 是对 swagger-ui 的封装，使得其可以使用 Spring 的服务。

2.1.对于后端开发人员来说：
(1) 不用再手写Wiki接口拼大量参数，避免手写错误
(2) 对代码侵入性低，采用全注解的方式，开发简单
(3) 方法参数名修改、新增、减少参数都可以直接生效，不用手动维护
(4) 缺点：增加了开发成本，写接口还得再写一套参数配置
2.2.对前端开发来说
(1) 后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然
(2) 联调方便，如果出了问题，直接测试接口，实时检查参数和返回值，就可以快速定位是前端还是后端的问题
2.3.对于测试
(1) 但对于测试没有前端界面UI的功能，可以直接用它来测试接口
(2) 操作简单，不用了解具体代码就可以操作

3. 常用的注解

这里只收集了一部分注解

4. 如何搭建一个swagger？
   4.1 Springfox与swagger的整合使用与关系
   swagger是一个流行的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础，对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）。
   OAS本身是一个API规范，它用于描述一整套API接口，包括一个接口是GET还是POST请求啊，有哪些参数哪些header啊，都会被包括在这个文件中。它在设计的时候通常是YAML格式，这种格式书写起来比较方便，而在网络中传输时又会以json形式居多，因为json的通用性比较强。
   由于Spring的流行，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来。而springfox则是从这个组件发展而来，同时springfox也是一个新的项目，本文仍然是使用其中的一个组件springfox-swagger2。
   pringfox-swagger2依然是依赖OSA规范文档，也就是一个描述API的json文件，而这个组件的功能就是帮助我们自动生成这个json文件，我们会用到的另外一个组件springfox-swagger-ui就是将这个json文件解析出来，用一种更友好的方式呈现出来

讯享网

<!--swagger 2.9.2目前是最新版本较稳定--> <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> 

4.2.2 创建swagger配置类

讯享网package com.xr.springbootquartz.controller;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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;

/
 * @author WuJia
 * @create 2019-1-3 19:16
 * 创建该API的基本信息（这些基本信息会展现在文档页面中）
 * 访问地址：http://127.0.0.1:8899/swagger-ui.html
 */
@EnableWebMvc
@EnableSwagger2
@Configuration
public class SwaggerConfig extends WebMvcConfigurationSupport{
    /
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com"))
                .paths(PathSelectors.any())
                .build();
    }
    /
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://127.0.0.1:8899/swagger-ui.html
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot集成swagger生成API文档")//标题
                .description("关于quartz的一些操作接口调用")//描述
                .contact(new Contact("WuJia", "https://blog.csdn.net/_36911145", "2892940836@.com"))//作者信息
                .version("6.6.6")//版本号
                .build();
    }
}

4.2.3 SpringBoot集成Swagger2遇到异常：请求不到swagger-ui.html


这个错误，是因为静态资源路径映射问题导致。或者忘了在配置类加@EnableWebMvc
我们在访问http://localhost/swagger-ui.html时，这个swagger-ui.html相关的所有前端静态文件都在springfox-swagger-ui-2.9.2.jar里面。
解决方案如下：

package com.xr.springbootquartz.controller;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/js/").addResourceLocations("classpath:/js/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

4.2.4 建一个Quartzcontroller类

讯享网package com.xr.springbootquartz.controller; import com.alibaba.fastjson.JSON; import com.alibaba.fastjson.JSONArray; import com.alibaba.fastjson.JSONObject; import com.xr.springbootquartz.job.ScheduledJob; import com.xr.springbootquartz.job.SchedulerManager; import com.xr.springbootquartz.model.Ttrigger; import com.xr.springbootquartz.service.TriggerService; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.quartz.JobKey; import org.quartz.Scheduler; import org.quartz.SchedulerException; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.scheduling.quartz.SchedulerFactoryBean; import org.springframework.stereotype.Controller; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RestController; import java.text.SimpleDateFormat; import java.util.Date; import java.util.HashMap; import java.util.List; / * @author: * @create: 2019-10-30 15:58 / @Api(value="aaaaaaa",description="Quartz的相关信息接口") @Controller @RestController public class QuartzController { @Autowired private SchedulerFactoryBean schedulerFactoryBean; @Autowired private TriggerService triggerService; //获得所有的作业任务 @ApiOperation(value="获取所有quartz定时任务",notes="获取所有job，无需参数", httpMethod = "POST") @RequestMapping("/getList") public String getList(){ List<Ttrigger> list=triggerService.getTrigger(); String jso = JSON.toJSONString(list); String UserJson = "{\"code\":0,\"msg\":\"\",\"count\":"+1+",\"data\":"+jso+"}"; return UserJson; } //测试更新 @ApiOperation(value="测试更新",notes="更新任务，无需", httpMethod = "POST") @RequestMapping("/start") public String start(){ triggerService.refreshTrigger(); return "更新成功"; } //新增作业 @ApiOperation(value="新增任务",notes="需要trigger，需要参数", httpMethod = "POST") @RequestMapping("/addJob") public String addJob(Ttrigger ttrigger){ SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");//设置日期格式 ttrigger.setAddTime(df.format(new Date()));// new Date()为获取当前系统时间 ttrigger.setState("1"); triggerService.add(ttrigger); triggerService.refreshTrigger(); System.out.println(ttrigger); return "新增成功"; } //暂停单个作业 @ApiOperation(value="暂停单个作业",notes="需要jobName和group，需要参数", httpMethod = "POST") @RequestMapping("/zanting") public String stop(Ttrigger ttrigger) throws SchedulerException { /* System.out.println(jobName+".."+group);*/ Scheduler scheduler = schedulerFactoryBean.getScheduler(); JobKey jobKey = new JobKey(ttrigger.getJobName(),ttrigger.getGroup()); /* System.out.println(jobKey); System.out.println("j: "+new JobKey("com.xr.springbootquartz.job.TestTask2","default"));*/ scheduler.pauseJob(jobKey); return "暂停成功"; } //批量暂停 @ApiOperation(value="批量餐厅任务",notes="需要jobName和group，需要参数", httpMethod = "POST") @RequestMapping("/moreZanting") public void moreZanting(String test) throws SchedulerException { //json转对象 List<Ttrigger> ttriggerList1 = JSON.parseArray(test, Ttrigger.class); for(Ttrigger ttrigger : ttriggerList1){ // Exception stop(ttrigger); } } / * 恢复单个定时任务 * * @throws SchedulerException */ @ApiOperation(value="恢复单个任务",notes="需要jobName和group，需要参数", httpMethod = "POST") @RequestMapping("/huifu") public void resumeJob(Ttrigger ttrigger) throws SchedulerException { /*System.out.println(ttrigger.getJobName()+"恢复任务"+ttrigger.getGroup()); System.out.println(getType(ttrigger.getJobName())); System.out.println(getType("com.xr.springbootquartz.job.TestTask2")); */ Scheduler scheduler = schedulerFactoryBean.getScheduler(); JobKey triggerKey = new JobKey(ttrigger.getJobName(),ttrigger.getGroup()); /* System.out.println(new JobKey(ttrigger.getJobName(),ttrigger.getGroup())); System.out.println("j: "+new JobKey("com.xr.springbootquartz.job.TestTask2","default"));*/ scheduler.resumeJob(triggerKey); } //批量恢复作业 @ApiOperation(value="批量恢复任务",notes="需要jobName和group，需要参数", httpMethod = "POST") @RequestMapping("/moreHuifu") public void test(String test) throws SchedulerException { //json转对象 List<Ttrigger> ttriggerList1 = JSON.parseArray(test, Ttrigger.class); for(Ttrigger ttrigger : ttriggerList1){ // Exception resumeJob(ttrigger); } } //删除单个作业 @ApiOperation(value="删除单个任务",notes="需要jobName和group，需要参数", httpMethod = "POST") @RequestMapping("/deleteJob") public void deleteJob(Ttrigger ttrigger) throws SchedulerException { Scheduler scheduler = schedulerFactoryBean.getScheduler(); JobKey jobKey = new JobKey(ttrigger.getJobName(), ttrigger.getGroup()); scheduler.deleteJob(jobKey); } @ApiOperation(value="批量删除任务",notes="需要jobName和group，需要参数", httpMethod = "POST") @RequestMapping("/moreDelete") public void moreDelete(String test) throws SchedulerException { /*List<SubTrade> subTrades = JSON.parseArray(json.getString("subTradeList"), SubTrade.class);*/ //json转对象 List<Ttrigger> ttriggerList1 = JSON.parseArray(test, Ttrigger.class); for(Ttrigger ttrigger : ttriggerList1){ // Exception deleteJob(ttrigger); } } } 

4.2.5 主程序启动后访问http://localhost:8899/swagger-ui.html
我设置的端口号是8899
可看到如下页面
注意controller类自己建

点击其中一个接口页面如下

点击try it out 进入接口调试，有参数输入参数，无参数直接执行 点击excute执行获得json数据如下