集成 Swagger2 构建强大的 RESTful API 文档

杀马特。学长 韩版系。学妹 提交于 2020-03-29 07:04:03

微信公众号:一个优秀的废人如有问题或建议,请后台留言,我会尽力解决你的问题。
前言

快过年了,不知道你们啥时候放年假,忙不忙。反正我是挺闲的,所以有时间写 blog。今天给你们带来 SpringBoot 集成 Swagger2 的教程。

什么是 Swagger2

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

为什么使用 Swagger2 ?

相信刚开始不熟悉 web 开发的时候,大家都有手写 Api 文档的时候。而手写 Api 文档主要有以下几个痛点:

文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。

接口返回结果不明确。

不能直接在线测试接口,通常需要使用工具,比如 postman。

接口文档太多,不好管理。

这些痛点在前后端分离的大型项目上显得尤为烦躁。而 Swagger2 的出现恰好能个解决这些痛点。因为 Swagger2 有以下功能:

文档自动更新,只要生成 Api 的网址没变,基本不需要跟前端沟通。

接口返回结果非常明确,包括数据类型,状态码,错误信息等。

可以直接在线测试文档,而且还有实例提供给你。

只需要一次配置便可使用,之后只要会有一份接口文档,非常易于管理。

集成演示

首先新建一个 SpringBoot 项目,还不会的参考我这篇旧文—— 如何使用 IDEA 构建 Spring Boot 工程

构建时,在选择依赖那一步勾选 Web、LomBok、JPA 和 Mysql 依赖。其中 Mysql 可以不勾,因为我这里用于操作实际的数据库,所以我勾选了。

生成 SpringBoot 后的 Pom 文件依赖如下:这里使用的是 2.4.0 的 Swagger2 版本。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.2.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.nasus</groupId>
    <artifactId>swagger2</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swagger2</name>
    <description>Demo project for Swagger2</description>
&lt;properties&gt;
    &lt;java.version&gt;1.8&lt;/java.version&gt;
&lt;/properties&gt;

&lt;dependencies&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
        &lt;artifactId&gt;spring-boot-starter-data-jpa&lt;/artifactId&gt;
    &lt;/dependency&gt;

    &lt;dependency&gt;
        &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
        &lt;artifactId&gt;spring-boot-starter-web&lt;/artifactId&gt;
    &lt;/dependency&gt;

    &lt;dependency&gt;
        &lt;groupId&gt;mysql&lt;/groupId&gt;
        &lt;artifactId&gt;mysql-connector-java&lt;/artifactId&gt;
        &lt;scope&gt;runtime&lt;/scope&gt;
    &lt;/dependency&gt;

    &lt;dependency&gt;
        &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
        &lt;artifactId&gt;spring-boot-starter-test&lt;/artifactId&gt;
        &lt;scope&gt;test&lt;/scope&gt;
    &lt;/dependency&gt;

    &lt;dependency&gt;
        &lt;groupId&gt;io.springfox&lt;/groupId&gt;
        &lt;artifactId&gt;springfox-swagger2&lt;/artifactId&gt;
        &lt;version&gt;2.4.0&lt;/version&gt;
    &lt;/dependency&gt;

    &lt;dependency&gt;
        &lt;groupId&gt;io.springfox&lt;/groupId&gt;
        &lt;artifactId&gt;springfox-swagger-ui&lt;/artifactId&gt;
        &lt;version&gt;2.4.0&lt;/version&gt;
    &lt;/dependency&gt;
&lt;/dependencies&gt;

&lt;build&gt;
    &lt;plugins&gt;
        &lt;plugin&gt;
            &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
            &lt;artifactId&gt;spring-boot-maven-plugin&lt;/artifactId&gt;
        &lt;/plugin&gt;
    &lt;/plugins&gt;
&lt;/build&gt;

</project>

第二步,在 SpringBoot 启动类(Application)的同级目录新建一个 Swagger 配置类,注意 Swagger2 配置类必须与项目入口类 Application 位于同一级目录,否则生成 Api 文档失败,代码如下:

package com.nasus;
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;
/**


Project Name:swagger2-demo <br/>


Package Name:com.nasus <br/>


Date:2019/1/22 22:52 <br/>


<b>Description:</b> TODO: 描述该类的作用 <br/>



@author <a href="turodog@foxmail.com">nasus</a><br/>


Copyright Notice =========================================================


This file contains proprietary information of Eastcom Technologies Co. Ltd.


Copying or reproduction without prior written approval is prohibited.


Copyright (c) 2019 =======================================================
*/
@Configuration
// 启用 Swagger2
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 文档信息对象
.apiInfo(apiInfo())
.select()
// 被注解的包路径
.apis(RequestHandlerSelectors.basePackage("com.nasus.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 标题
.title("springboot 利用 swagger 构建 API 文档")
// Api 文档描述
.description("简单优雅的 restful 风格,https://blog.csdn.net/turodog/")
         .termsOfServiceUrl("https://blog.csdn.net/turodog/")
         // 文档作者信息
         .contact(new Contact("陈志远", "https://github.com/turoDog", "turodog@foxmail.com"))
         // 文档版本
         .version("1.0")
         .build();

}
}

第三步,配置被注解的 Controller 类,编写各个接口的请求参数,返回结果,接口描述等等,代码如下:

package com.nasus.controller;
import com.nasus.entity.Student;
import com.nasus.service.StudentService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
/**


Project Name:swagger2-demo <br/>


Package Name:com.nasus.controller <br/>


Date:2019/1/22 22:07 <br/>


<b>Description:</b> TODO: 描述该类的作用 <br/>



@author <a href="turodog@foxmail.com">nasus</a><br/>


Copyright Notice =========================================================


This file contains proprietary information of Eastcom Technologies Co. Ltd.


Copying or reproduction without prior written approval is prohibited.


Copyright (c) 2019 =======================================================
*/
@RestController
@RequestMapping("/student")
// @Api:修饰整个类,描述Controller的作用
@Api("StudentController Api 接口文档")
public class StudentController {
@Autowired
private StudentService studentService;
// @ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiOperation(value="获取所有学生列表", notes="获取所有学生列表")
@RequestMapping(value={""}, method= RequestMethod.GET)
public List<Student> getStudent() {
List<Student> list = studentService.findAll();
return list;
}
@ApiOperation(value="添加学生信息", notes="添加学生信息")
// @ApiImplicitParam:一个请求参数
@ApiImplicitParam(name = "student", value = "学生信息详细实体", required = true, dataType = "Student")
@PostMapping("/save")
public Student save(@RequestBody Student student){
return studentService.save(student);
}
@ApiOperation(value="获学生信息", notes="根据url的id来获取学生详细信息")
@ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Integer",paramType = "path")
@GetMapping("/{id}")
public Student findById(@PathVariable("id") Integer id){
return studentService.findById(id);
}
@ApiOperation(value="删除学生", notes="根据url的id来指定删除的学生")
@ApiImplicitParam(name = "id", value = "学生ID", required = true, dataType = "Integer",paramType = "path")
@DeleteMapping("/{id}")
public String deleteById(@PathVariable("id") Integer id){
studentService.delete(id);
return "success";
}
@ApiOperation(value="更新学生信息", notes="根据url的id来指定更新学生信息")
// @ApiImplicitParams:多个请求参数
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "学生ID", required = true, dataType = "Integer",paramType = "path"),
@ApiImplicitParam(name = "student", value = "学生实体student", required = true, dataType = "Student")
})
@PutMapping(value="/{id}")
public String updateStudent(@PathVariable Integer id, @RequestBody Student student) {
Student oldStudent = this.findById(id);
oldStudent.setId(student.getId());
oldStudent.setName(student.getName());
oldStudent.setAge(student.getAge());
studentService.save(oldStudent);
return "success";
}
// 使用该注解忽略这个API
@ApiIgnore
@RequestMapping(value = "/hi", method = RequestMethod.GET)
public String  jsonTest() {
return " hi you!";
}
}

第四步,启动项目,访问 http://localhost:8080/swagger-ui.html 地址,结果如下图:

项目源代码

github

图解接口

Swagger2 常用注解简介
@ApiOperation:用在方法上,说明方法的作用
  1.value: 表示接口名称
  2.notes: 表示接口详细描述 
@ApiImplicitParams:用在方法上包含一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
  1.paramType:参数位置
  2.header 对应注解:@RequestHeader
  3.query 对应注解:@RequestParam
  4.path  对应注解: @PathVariable
  5.body 对应注解: @RequestBody
  6.name:参数名
  7.dataType:参数类型
  8.required:参数是否必须传
  9.value:参数的描述
  10.defaultValue:参数的默认值
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
  1.code:状态码
  2.message:返回自定义信息
  3.response:抛出异常的类
@ApiIgnore: 表示该接口函数不对swagger2开放展示
@Api:修饰整个类,描述Controller的作用
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
注意事项

@ApiImplicitParam 注解下的 paramType 属性,会影响接口的测试,如果设置的属性跟spring 的注解对应不上,会获取不到参数,例如 paramType=path ,函数内却使用@RequestParam 注解,这样,可能会获取不到传递进来的参数,需要按照上面进行对应,将 @RequestParam 注解改为 @PathVariable 才能获取到对应的参数。

后语

以上就是我对 Swagger2 的理解与使用,以上只是教大家入门 Swagger2 ,想要深入使用还是希望自行查阅官方文档。最后,对 Python 、Java 感兴趣请长按二维码关注一波,我会努力带给你们价值,如果觉得本文对你哪怕有一丁点帮助,请帮忙点好看,让更多人知道。

    <div class="fenyetiao"><pre>文章来源:segmentfault,作者:一个优秀的废人。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件至:william.shi#ucloud.cn(邮箱中#请改为@)进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容。</pre></div>

原文地址:https://www.cnblogs.com/java-zhao/p/5348113.html

微信公众号:一个优秀的废人如有问题或建议,请后台留言,我会尽力解决你的问题。
前言

快过年了,不知道你们啥时候放年假,忙不忙。反正我是挺闲的,所以有时间写 blog。今天给你们带来 SpringBoot 集成 Swagger2 的教程。

什么是 Swagger2

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

为什么使用 Swagger2 ?

相信刚开始不熟悉 web 开发的时候,大家都有手写 Api 文档的时候。而手写 Api 文档主要有以下几个痛点:

文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。

接口返回结果不明确。

不能直接在线测试接口,通常需要使用工具,比如 postman。

接口文档太多,不好管理。

这些痛点在前后端分离的大型项目上显得尤为烦躁。而 Swagger2 的出现恰好能个解决这些痛点。因为 Swagger2 有以下功能:

文档自动更新,只要生成 Api 的网址没变,基本不需要跟前端沟通。

接口返回结果非常明确,包括数据类型,状态码,错误信息等。

可以直接在线测试文档,而且还有实例提供给你。

只需要一次配置便可使用,之后只要会有一份接口文档,非常易于管理。

集成演示

首先新建一个 SpringBoot 项目,还不会的参考我这篇旧文—— 如何使用 IDEA 构建 Spring Boot 工程

构建时,在选择依赖那一步勾选 Web、LomBok、JPA 和 Mysql 依赖。其中 Mysql 可以不勾,因为我这里用于操作实际的数据库,所以我勾选了。

生成 SpringBoot 后的 Pom 文件依赖如下:这里使用的是 2.4.0 的 Swagger2 版本。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.2.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.nasus</groupId>
    <artifactId>swagger2</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swagger2</name>
    <description>Demo project for Swagger2</description>
&lt;properties&gt;
    &lt;java.version&gt;1.8&lt;/java.version&gt;
&lt;/properties&gt;

&lt;dependencies&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
        &lt;artifactId&gt;spring-boot-starter-data-jpa&lt;/artifactId&gt;
    &lt;/dependency&gt;

    &lt;dependency&gt;
        &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
        &lt;artifactId&gt;spring-boot-starter-web&lt;/artifactId&gt;
    &lt;/dependency&gt;

    &lt;dependency&gt;
        &lt;groupId&gt;mysql&lt;/groupId&gt;
        &lt;artifactId&gt;mysql-connector-java&lt;/artifactId&gt;
        &lt;scope&gt;runtime&lt;/scope&gt;
    &lt;/dependency&gt;

    &lt;dependency&gt;
        &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
        &lt;artifactId&gt;spring-boot-starter-test&lt;/artifactId&gt;
        &lt;scope&gt;test&lt;/scope&gt;
    &lt;/dependency&gt;

    &lt;dependency&gt;
        &lt;groupId&gt;io.springfox&lt;/groupId&gt;
        &lt;artifactId&gt;springfox-swagger2&lt;/artifactId&gt;
        &lt;version&gt;2.4.0&lt;/version&gt;
    &lt;/dependency&gt;

    &lt;dependency&gt;
        &lt;groupId&gt;io.springfox&lt;/groupId&gt;
        &lt;artifactId&gt;springfox-swagger-ui&lt;/artifactId&gt;
        &lt;version&gt;2.4.0&lt;/version&gt;
    &lt;/dependency&gt;
&lt;/dependencies&gt;

&lt;build&gt;
    &lt;plugins&gt;
        &lt;plugin&gt;
            &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
            &lt;artifactId&gt;spring-boot-maven-plugin&lt;/artifactId&gt;
        &lt;/plugin&gt;
    &lt;/plugins&gt;
&lt;/build&gt;

</project>

第二步,在 SpringBoot 启动类(Application)的同级目录新建一个 Swagger 配置类,注意 Swagger2 配置类必须与项目入口类 Application 位于同一级目录,否则生成 Api 文档失败,代码如下:

package com.nasus;
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;
/**


Project Name:swagger2-demo <br/>


Package Name:com.nasus <br/>


Date:2019/1/22 22:52 <br/>


<b>Description:</b> TODO: 描述该类的作用 <br/>



@author <a href="turodog@foxmail.com">nasus</a><br/>


Copyright Notice =========================================================


This file contains proprietary information of Eastcom Technologies Co. Ltd.


Copying or reproduction without prior written approval is prohibited.


Copyright (c) 2019 =======================================================
*/
@Configuration
// 启用 Swagger2
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 文档信息对象
.apiInfo(apiInfo())
.select()
// 被注解的包路径
.apis(RequestHandlerSelectors.basePackage("com.nasus.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 标题
.title("springboot 利用 swagger 构建 API 文档")
// Api 文档描述
.description("简单优雅的 restful 风格,https://blog.csdn.net/turodog/")
         .termsOfServiceUrl("https://blog.csdn.net/turodog/")
         // 文档作者信息
         .contact(new Contact("陈志远", "https://github.com/turoDog", "turodog@foxmail.com"))
         // 文档版本
         .version("1.0")
         .build();

}
}

第三步,配置被注解的 Controller 类,编写各个接口的请求参数,返回结果,接口描述等等,代码如下:

package com.nasus.controller;
import com.nasus.entity.Student;
import com.nasus.service.StudentService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
/**


Project Name:swagger2-demo <br/>


Package Name:com.nasus.controller <br/>


Date:2019/1/22 22:07 <br/>


<b>Description:</b> TODO: 描述该类的作用 <br/>



@author <a href="turodog@foxmail.com">nasus</a><br/>


Copyright Notice =========================================================


This file contains proprietary information of Eastcom Technologies Co. Ltd.


Copying or reproduction without prior written approval is prohibited.


Copyright (c) 2019 =======================================================
*/
@RestController
@RequestMapping("/student")
// @Api:修饰整个类,描述Controller的作用
@Api("StudentController Api 接口文档")
public class StudentController {
@Autowired
private StudentService studentService;
// @ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiOperation(value="获取所有学生列表", notes="获取所有学生列表")
@RequestMapping(value={""}, method= RequestMethod.GET)
public List<Student> getStudent() {
List<Student> list = studentService.findAll();
return list;
}
@ApiOperation(value="添加学生信息", notes="添加学生信息")
// @ApiImplicitParam:一个请求参数
@ApiImplicitParam(name = "student", value = "学生信息详细实体", required = true, dataType = "Student")
@PostMapping("/save")
public Student save(@RequestBody Student student){
return studentService.save(student);
}
@ApiOperation(value="获学生信息", notes="根据url的id来获取学生详细信息")
@ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Integer",paramType = "path")
@GetMapping("/{id}")
public Student findById(@PathVariable("id") Integer id){
return studentService.findById(id);
}
@ApiOperation(value="删除学生", notes="根据url的id来指定删除的学生")
@ApiImplicitParam(name = "id", value = "学生ID", required = true, dataType = "Integer",paramType = "path")
@DeleteMapping("/{id}")
public String deleteById(@PathVariable("id") Integer id){
studentService.delete(id);
return "success";
}
@ApiOperation(value="更新学生信息", notes="根据url的id来指定更新学生信息")
// @ApiImplicitParams:多个请求参数
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "学生ID", required = true, dataType = "Integer",paramType = "path"),
@ApiImplicitParam(name = "student", value = "学生实体student", required = true, dataType = "Student")
})
@PutMapping(value="/{id}")
public String updateStudent(@PathVariable Integer id, @RequestBody Student student) {
Student oldStudent = this.findById(id);
oldStudent.setId(student.getId());
oldStudent.setName(student.getName());
oldStudent.setAge(student.getAge());
studentService.save(oldStudent);
return "success";
}
// 使用该注解忽略这个API
@ApiIgnore
@RequestMapping(value = "/hi", method = RequestMethod.GET)
public String  jsonTest() {
return " hi you!";
}
}

第四步,启动项目,访问 http://localhost:8080/swagger-ui.html 地址,结果如下图:

项目源代码

github

图解接口

Swagger2 常用注解简介
@ApiOperation:用在方法上,说明方法的作用
  1.value: 表示接口名称
  2.notes: 表示接口详细描述 
@ApiImplicitParams:用在方法上包含一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
  1.paramType:参数位置
  2.header 对应注解:@RequestHeader
  3.query 对应注解:@RequestParam
  4.path  对应注解: @PathVariable
  5.body 对应注解: @RequestBody
  6.name:参数名
  7.dataType:参数类型
  8.required:参数是否必须传
  9.value:参数的描述
  10.defaultValue:参数的默认值
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
  1.code:状态码
  2.message:返回自定义信息
  3.response:抛出异常的类
@ApiIgnore: 表示该接口函数不对swagger2开放展示
@Api:修饰整个类,描述Controller的作用
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
注意事项

@ApiImplicitParam 注解下的 paramType 属性,会影响接口的测试,如果设置的属性跟spring 的注解对应不上,会获取不到参数,例如 paramType=path ,函数内却使用@RequestParam 注解,这样,可能会获取不到传递进来的参数,需要按照上面进行对应,将 @RequestParam 注解改为 @PathVariable 才能获取到对应的参数。

后语

以上就是我对 Swagger2 的理解与使用,以上只是教大家入门 Swagger2 ,想要深入使用还是希望自行查阅官方文档。最后,对 Python 、Java 感兴趣请长按二维码关注一波,我会努力带给你们价值,如果觉得本文对你哪怕有一丁点帮助,请帮忙点好看,让更多人知道。

    <div class="fenyetiao"><pre>文章来源:segmentfault,作者:一个优秀的废人。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件至:william.shi#ucloud.cn(邮箱中#请改为@)进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容。</pre></div>

原文地址:https://www.cnblogs.com/java-zhao/p/5348113.html

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!