【Swagger2】springboot整合swagger2

Swagger 简介

  Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

Swagger集成

添加pom依赖

     <!--swagger 在线接口生成插件-->
        <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>
        <!-- 解决FluentIterable.class找不到问题 -->
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>23.0</version>
        </dependency>
        <!-- java8 不需要添加,高版本需要添加 -->
        <dependency>
            <groupId>javax.xml.bind</groupId>
            <artifactId>jaxb-api</artifactId>
            <version>2.3.0</version>
        </dependency>

添加配置文件

@Configuration@EnableSwagger2public class Swagger2 implements WebMvcConfigurer {

    /**     * 创建API应用     * apiInfo() 增加API相关信息     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,     * 本例采用指定扫描的包路径来定义指定要建立API的目录。     *     * @return     */    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))                         //这里采用包含注解的方式来确定要显示的接口                .paths(PathSelectors.any())                .build();    }

    /**     * 创建该API的基本信息(这些基本信息会展现在文档页面中)     * 访问地址:http://项目实际地址/swagger-ui.html     * @return     */    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("leader2.0 在线api文档")                .description("leader2.0 在线api文档")                .version("1.0")                .build();    }

    /**     * 静态资源配置     * @return     */    @Override    public void addResourceHandlers(ResourceHandlerRegistry registry) {        registry.addResourceHandler("/**")                .addResourceLocations("classpath:/static/");

        registry.addResourceHandler("swagger-ui.html")                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")                .addResourceLocations("classpath:/META-INF/resources/webjars/");    }

}

通过createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息。

开启swagger

启动类中添加 @EnableSwagger2注解,开启swagger;

@SpringBootApplication
@EnableSwagger2
public class Application {

    public static void main(String[] args) {
        new SpringApplicationBuilder(Application.class)
                .run(args);
    }
}

Swagger注解

@Api:用在类上,说明该类的作用。

@ApiOperation:注解来给API增加方法说明。

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

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

@ApiResponses:用于表示一组响应

@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息

l   code:数字,例如400

l   message:信息,例如"请求参数没填好"

l   response:抛出异常的类

@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)

l   @ApiModelProperty:描述一个model的属性

注意:@ApiImplicitParam的参数说明:

paramType:指定参数放在哪个地方
header:请求参数放置于Request Header,使用@RequestHeader获取

query:请求参数放置于请求地址,使用@RequestParam获取

path:(用于restful接口)-->请求参数的获取:@PathVariable

body:(不常用)

form(不常用)

name:参数名  
dataType:参数类型  
required:参数是否必须传 true | false
value:说明参数的意思  
defaultValue:参数的默认值  

使用事例

@RestController
@RequestMapping("/fdfs")
public class FastDFSController {
    @Autowired
    private FastDFSClient fdfsClient;

    /**
     * 文件上传
     * @param file
     * @return
     * @throws Exception
     */
    @ApiOperation(value = "上传文件", notes = "选择文件上传")
    @ApiImplicitParam(name = "file",paramType= "File",value = "选择上上传的文件",required = true)
    @RequestMapping(value = "/upload",method = RequestMethod.POST,produces = MediaType.APPLICATION_JSON,headers = "content-type=multipart/form-data")
    public Map<String,Object> upload(MultipartFile file) throws Exception{
        Boolean ifsize = CheckFileSize.check(file,10240,"M");
        Map<String,Object> result = new HashMap<>();
        if(ifsize){
            String url = fdfsClient.uploadFile(file);
            result.put("code", 200);
            result.put("msg", "上传成功");
            result.put("filename",file.getOriginalFilename());
            String extname = file.getOriginalFilename().split("\\.")[1];
            result.put("extname",extname);
            if (!"jpg".equals(extname) && !"jpeg".equals(extname) && !"png".equals(extname)){
                result.put("url", url + "?attname=" + file.getOriginalFilename());
            }else {
                result.put("url", url);
            }
        }else {
            result.put("code", 500);
            result.put("msg", "允许上传最大为10G!");
        }
        return result;
    }

    /**
     * 文件下载
     * @param fileUrl  url 开头从组名开始
     * @param response
     * @throws Exception
     */
    @ApiOperation(value = "下载文件", notes = "根据url下载文件")
    @ApiImplicitParams({@ApiImplicitParam(name = "fileUrl",value = "文件路径")})
    @RequestMapping(value = "/download",method = RequestMethod.GET,produces = MediaType.APPLICATION_JSON)
    public void  download(String fileUrl, HttpServletResponse response) throws Exception{

        byte[] data = fdfsClient.download(fileUrl);

        response.setCharacterEncoding("UTF-8");
        response.setHeader("Content-disposition", "attachment;filename=" + URLEncoder.encode("test.7z", "UTF-8"));

        // 写出
        ServletOutputStream outputStream = response.getOutputStream();
        IOUtils.write(data, outputStream);
    }

}

访问

启动springboot后,浏览器 ip:port/swagger-ui.html

原文地址:https://www.cnblogs.com/jxd283465/p/11714003.html

时间: 2024-11-08 21:38:39

【Swagger2】springboot整合swagger2的相关文章

5分钟 springboot 整合swagger2

springboot 整合swagger2 1.maven配置文件中添加依赖 <properties> <swagger2.version>2.2.2</swagger2.version> </properties> -------------------------------------------------- <dependency> <groupId>io.springfox</groupId> <arti

SpringBoot整合Swagger2

手写Api文档的几个痛点: 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时. 接口返回结果不明确 不能直接在线测试接口,通常需要使用工具,比如postman 接口文档太多,不好管理 Swagger也就是为了解决这个问题,当然也不能说Swagger就一定是完美的,当然也有缺点,最明显的就是代码移入性比较强. 其他的不多说,想要了解Swagger的,可以去Swagger官网,可以直接使用Swagger editor编写接口文档,当然我们这里讲解的是SpringBoot整合Swa

Spring Boot2 系列教程(十七)SpringBoot 整合 Swagger2

前后端分离后,维护接口文档基本上是必不可少的工作. 一个理想的状态是设计好后,接口文档发给前端和后端,大伙按照既定的规则各自开发,开发好了对接上了就可以上线了.当然这是一种非常理想的状态,实际开发中却很少遇到这样的情况,接口总是在不断的变化之中,有变化就要去维护,做过的小伙伴都知道这件事有多么头大!还好,有一些工具可以减轻我们的工作量,Swagger2 就是其中之一,至于其他类似功能但是却收费的软件,这里就不做过多介绍了.本文主要和大伙来聊下 在Spring Boot 中如何整合 Swagger

Spring Mvc和SpringBoot整合Swagger2

各位同学大家好,最近项目赶进度,没有钻研技术的时间,但碰巧今天需要在Spring项目上进行SpringMvc和Swagger的整合,而第一次使用Swagger是在SpringBoot项目上,因此踩了不少的坑,于是想和大家分享一下 :关于Swagger在SpringBoot或者和SpringMvc的集成! 随着开发模式逐渐向前后端分离演变,沟通的成本逐渐增加,前端和后端的唯一联系,变成了API接口:API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API

(六)SpringBoot整合Swagger2框架

一:什么是Swagger Swagger是一款通过我们添加的注解来对方法进行说明,来自动生成项目的在线api接口文档的web服务. 二:添加Swagger2依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.4.0</version> </dependency>

SpringBoot整合Swagger2搭建API在线文档

Swagger,中文"拽"的意思,它是一个功能强大的在线API在线文档,目前它的版本为2.x,所以称为Swagger2.Swagger2提供了在线文档的查阅和测试功能.利用Swagger2很容易构建RESTful风格的API,在SpringBoot中集成Swagger2,步骤如下. 1.引入依赖 <!--Swagger2--> <dependency> <groupId>io.springfox</groupId> <artifac

[idea] SpringBoot整合swagger2实现CRUD

一:创建SpringBoot ,在pom.xml文件中加入jar包 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version></dependency><dependency> <groupId>io.springfox&

SpringBoot(六) SpringBoot整合Swagger2(自动化生成接口文档)

一:在上篇文章pom增加依赖: <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId>

SpringBoot整合Swagger2简单的例子

Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步.Swagger 让部署管理和使用功能强大的API从未如此简单. 这里我给大家带来一个简单的整合DEMO 先来看项目结构 下面是基本的步骤 一.添加MAVEN依赖 <dependency> <groupId>io.springfox</gro