Swagger使用

Posted edda

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了Swagger使用相关的知识，希望对你有一定的参考价值。

一、简介

https://swagger.io/tools/swagger-ui/

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

作用

  • 接口的文档在线自动生成
  • 功能测试

Swagger是一组开源项目，其中主要要项目如下

  •   Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
  •  Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。
  • Swagger-js: 用于javascript的Swagger实现。
  • Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
  • Swagger-ui：一个无依赖的html、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
  • Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码

二、测试Demo

（1）创建项目

创建一个spring boot项目

技术图片

（2）依赖

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  3. 	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  4. 	<modelVersion>4.0.0</modelVersion>
  5. 	<parent>
  6. 		<groupId>org.springframework.boot</groupId>
  7. 		<artifactId>spring-boot-starter-parent</artifactId>
  8. 		<version>2.1.7.RELEASE</version>
  9. 		<relativePath/> <!-- lookup parent from repository -->
  10. 	</parent>
  11. 	<groupId>com.example</groupId>
  12. 	<artifactId>swagger</artifactId>
  13. 	<version>0.0.1-SNAPSHOT</version>
  14. 	<name>swagger</name>
  15. 	<description>Demo project for Spring Boot</description>
  16.  
  17. 	<properties>
  18. 		<java.version>1.8</java.version>
  19. 	</properties>
  20.  
  21. 	<dependencies>
  22. 		<!--Swagger依赖-->
  23. 		<dependency>
  24. 		<groupId>io.springfox</groupId>
  25. 		<artifactId>springfox-swagger2</artifactId>
  26. 		<version>2.9.2</version>
  27. 		</dependency>
  28.  
  29. 		<dependency>
  30. 			<groupId>io.springfox</groupId>
  31. 			<artifactId>springfox-swagger-ui</artifactId>
  32. 			<version>2.9.2</version>
  33. 		</dependency>
  34.  
  35. 		<!--hibernate校验依赖 -->
  36. 		<dependency>
  37. 			<groupId>org.hibernate</groupId>
  38. 			<artifactId>hibernate-validator</artifactId>
  39. 			<version>6.0.16.Final</version>
  40. 		</dependency>
  41.  
  42. 		<dependency>
  43. 			<groupId>org.springframework.boot</groupId>
  44. 			<artifactId>spring-boot-starter</artifactId>
  45. 		</dependency>
  46.  
  47. 		<dependency>
  48. 			<groupId>org.springframework.boot</groupId>
  49. 			<artifactId>spring-boot-starter-web</artifactId>
  50. 		</dependency>
  51.  
  52. 		<dependency>
  53. 			<groupId>com.fasterxml.jackson.core</groupId>
  54. 			<artifactId>jackson-annotations</artifactId>
  55. 			<version>2.9.0</version>
  56. 		</dependency>
  57. 	</dependencies>
  58.  
  59. 	<build>
  60. 		<plugins>
  61. 			<plugin>
  62. 				<groupId>org.springframework.boot</groupId>
  63. 				<artifactId>spring-boot-maven-plugin</artifactId>
  64. 			</plugin>
  65. 		</plugins>
  66. 	</build>
  67.  
  68. </project>

（3）application.properties配置

  1. #https://blog.csdn.net/z_k_h/article/details/81875828(为啥配置)
  2. logging.level.io.swagger.models.parameters.AbstractSerializableParameter=error

（4）Swagger2配置类

  1. package cn.zzq.config;
  2.  
  3. import org.springframework.context.annotation.Bean;
  4. import org.springframework.context.annotation.ComponentScan;
  5. import org.springframework.context.annotation.Configuration;
  6. import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
  7. import springfox.documentation.builders.ApiInfoBuilder;
  8. import springfox.documentation.builders.PathSelectors;
  9. import springfox.documentation.builders.RequestHandlerSelectors;
  10. import springfox.documentation.service.ApiInfo;
  11. import springfox.documentation.service.Contact;
  12. import springfox.documentation.spi.DocumentationType;
  13. import springfox.documentation.spring.web.plugins.Docket;
  14. import springfox.documentation.swagger2.annotations.EnableSwagger2;
  15.  
  16.  
  17. @EnableSwagger2
  18. @ComponentScan(basePackages = {"cn.zzq.controller"})
  19. @Configuration
  20. public class SwaggerConfig implements  WebMvcConfigurer {
  21.     @Bean
  22.     public Docket createRestApi() {
  23.         return new Docket(DocumentationType.SWAGGER_2)
  24.                 .apiInfo(apiInfo())
  25.                 .select()
  26.                 .apis(RequestHandlerSelectors.any())
  27.                 .paths(PathSelectors.any())
  28.                 .build();
  29.     }
  30.     private ApiInfo apiInfo() {
  31.         return new ApiInfoBuilder()
  32.                 .title("《SwaggerDemo的演示案例--》")//标题
  33.                 .description("description:项目摘要")//描述
  34.                 .termsOfServiceUrl("http://www.google.com.hk")//（不可见）条款地址，公司内部使用的话不需要配
  35.                 .contact(new Contact("Devil", "http://www.google.com.hk", "xx@qq.com"))//作者信息
  36.                 .version("2.9.2")//版本号
  37.                 .build();
  38.     }
  39. }

如上代码所示，通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）

（5）JsonResult

  1. package cn.zzq.bean;
  2.  
  3.  
  4. public class JsonResult {
  5.  
  6.     private String code;
  7.  
  8.     private String msg;
  9.  
  10.     private Object data;
  11.  
  12.     private int totalPage;
  13.  
  14.  
  15.     public String getCode() {
  16.         return code;
  17.     }
  18.  
  19.     public void setCode(String code) {
  20.         this.code = code;
  21.     }
  22.  
  23.     public String getMsg() {
  24.         return msg;
  25.     }
  26.  
  27.     public void setMsg(String msg) {
  28.         this.msg = msg;
  29.     }
  30.  
  31.     public Object getData() {
  32.         return data;
  33.     }
  34.  
  35.     public void setData(Object data) {
  36.         this.data = data;
  37.     }
  38.  
  39.     public int getTotalPage() {
  40.         return totalPage;
  41.     }
  42.  
  43.     public void setTotalPage(int totalPage) {
  44.         this.totalPage = totalPage;
  45.     }
  46.  
  47.  
  48.     public void success() {
  49.         this.code = "200";
  50.         this.msg = "请求成功！";
  51.     }
  52.  
  53.     public void success(Object data) {
  54.         success();
  55.         this.data = data;
  56.     }
  57.  
  58.     public void success(String msg) {
  59.         success();
  60.         this.msg = msg;
  61.     }
  62.  
  63.     public void failure() {
  64.         this.code = "500";
  65.         this.msg = "请求失败！";
  66.     }
  67.  
  68.     public void failure(String msg) {
  69.         failure();
  70.         this.msg = msg;
  71.     }
  72.  
  73.     public void setFailure(Integer code, String msg) {
  74.         this.code = code + "";
  75.         this.msg = msg;
  76.     }
  77. }

（6）User

  1. package cn.zzq.bean;
  2.  
  3. import io.swagger.annotations.ApiModelProperty;
  4.  
  5. import javax.validation.constraints.*;
  6.  
  7. public class User {
  8.     @ApiModelProperty(value="用户名")
  9.     @NotEmpty(message="姓名不能为空")
  10.     private String name;
  11.  
  12.     @ApiModelProperty(value="密码")
  13.     @NotEmpty(message="密码不能为空")
  14.     private String password;
  15.  
  16.     @ApiModelProperty(value="性别")
  17.     @NotEmpty(message="性别不能为空")
  18.     private String gender;
  19.  
  20.     @ApiModelProperty(value="年龄")
  21.     @NotNull(message="年龄不能为空")
  22.     @Min(value=18,message="必须年满18岁！")
  23.     @Max(value=30,message="年龄不能大于30岁！")
  24.     private Integer age;
  25.  
  26.     public String getName() {
  27.         return name;
  28.     }
  29.  
  30.     public void setName(String name) {
  31.         this.name = name;
  32.     }
  33.  
  34.     public String getPassword() {
  35.         return password;
  36.     }
  37.  
  38.     public void setPassword(String password) {
  39.         this.password = password;
  40.     }
  41.  
  42.     public String getGender() {
  43.         return gender;
  44.     }
  45.  
  46.     public void setGender(String gender) {
  47.         this.gender = gender;
  48.     }
  49.  
  50.     public Integer getAge() {
  51.         return age;
  52.     }
  53.  
  54.     public void setAge(Integer age) {
  55.         this.age = age;
  56.     }
  57. }

（7）UserController

  1. package cn.zzq.controller;
  2.  
  3. import cn.zzq.bean.JsonResult;
  4. import cn.zzq.bean.User;
  5. import io.swagger.annotations.*;
  6. import org.springframework.http.HttpStatus;
  7. import org.springframework.util.StringUtils;
  8. import org.springframework.validation.BindingResult;
  9. import org.springframework.validation.FieldError;
  10. import org.springframework.web.bind.annotation.*;
  11. import javax.validation.Valid;
  12. import java.util.ArrayList;
  13. import java.util.List;
  14.  
  15. @Api(value="User的相关信息接口",description="User的相关信息接口", protocols="http")
  16. @RestController
  17. public class UserController {
  18.  
  19.     @ApiOperation(notes="获取所有user，无需参数",value="获取所有user", httpMethod = "GET")
  20.     @GetMapping("/getAll")
  21.     public Object getAll(){
  22.         //查出的所有部门信息
  23.         List<User> list = new ArrayList<User>();
  24.         User user = new User();
  25.         user.setAge(23);
  26.         user.setGender("男");
  27.         user.setName("zhangsan");
  28.         user.setPassword("123456");
  29.         list.add(user);
  30.         return list;
  31.     }
  32.  
  33.     @ApiOperation(value="获取单个user", notes="传入json格式",httpMethod = "POST")
  34.     @PostMapping("/getOne")
  35.     public Object getOne(@RequestBody @Valid User user, BindingResult result){
  36.         JsonResult jsonResult = new JsonResult();
  37.         if(result.hasErrors()){
  38.             List<FieldError> fieldErrors = result.getFieldErrors();
  39.             for(int i=0;i<fieldErrors.size();i++){
  40.                 //控制台打印不符合校验的字段名和错误提示
  41.                 System.out.println("error field is :"+fieldErrors.get(i).getField()+",message is :"+fieldErrors.get(i).getDefaultMessage());
  42.                 String errorMsg = fieldErrors.get(i).getDefaultMessage();
  43.                 if(!StringUtils.isEmpty(errorMsg)){
  44.                     jsonResult.setFailure(HttpStatus.BAD_REQUEST.value(),errorMsg);
  45.                     return jsonResult;
  46.                 }
  47.             }
  48.         }
  49.         jsonResult.setFailure(HttpStatus.OK.value(),HttpStatus.OK.getReasonPhrase());
  50.         return jsonResult;
  51.     }
  52.  
  53.  
  54.     @ApiOperation(value="根据名称获取user",notes="传入json格式")
  55.     @ApiResponses({
  56.             @ApiResponse(code = 200, message = "请求成功"),
  57.             @ApiResponse(code = 500, message = "请求失败,后台服务出现异常"),
  58.             @ApiResponse(code = 401, message = "代表此操作无权限访问"),
  59.             @ApiResponse(code = 400, message = "表示请求参数错误"),
  60.     })
  61.     @PostMapping("/getOneByName")
  62.     public Object getOneByName(@ApiParam(value = "用户名", required = true)  @RequestBody  String name){
  63.         User u = new User();
  64.         u.setAge(23);
  65.         u.setGender("男");
  66.         u.setName(name);
  67.         u.setPassword("123456");
  68.         return u;
  69.     }
  70.  
  71.     @ApiOperation(value="修改用户",notes="参数非json格式", httpMethod="POST")
  72.     @ApiImplicitParams({
  73.             @ApiImplicitParam(paramType="query", name = "name", value = "用户名", required = true, dataType = "String"),
  74.             @ApiImplicitParam(paramType="query", name = "possword", value = "密码", required = true, dataType = "String")
  75.     })
  76.     @PostMapping("/update")
  77.     public Object update(String name,String possword){
  78.         User u = new User();
  79.         u.setAge(23);
  80.         u.setGender("男");
  81.         u.setName(name);
  82.         u.setPassword(possword);
  83.         return u;
  84.     }
  85. }

（7）启动类

  1. package cn.zzq;
  2.  
  3. import org.springframework.boot.SpringApplication;
  4. import org.springframework.boot.autoconfigure.SpringBootApplication;
  5. import springfox.documentation.swagger2.annotations.EnableSwagger2;
  6.  
  7. @SpringBootApplication
  8. public class SwaggerApplication {
  9.  
  10. 	public static void main(String[] args) {
  11. 		SpringApplication.run(SwaggerApplication.class, args);
  12. 	}
  13. }

（8）效果

http://localhost:8080/swagger-ui.html

技术图片

三、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获取

		<p>query：请求参数放置于请求地址，使用@RequestParam获取</p>

		<p>path：（用于restful接口）--&gt;请求参数的获取：@PathVariable</p>

		<p>body：（不常用）</p>

		<p>form（不常用）</p>
		</td>
	</tr><tr><td>
		<p>name：参数名</p>
		</td>
		<td>
		<p>&nbsp;</p>
		</td>
	</tr><tr><td>
		<p>dataType：参数类型</p>
		</td>
		<td>
		<p>&nbsp;</p>
		</td>
	</tr><tr><td>
		<p>required：参数是否必须传</p>
		</td>
		<td>
		<p>true | false</p>
		</td>
	</tr><tr><td>
		<p>value：说明参数的意思</p>
		</td>
		<td>
		<p>&nbsp;</p>
		</td>
	</tr><tr><td>
		<p>defaultValue：参数的默认值</p>
		</td>
		<td>
		<p>&nbsp;</p>
		</td>
	</tr></tbody></table></div><p>swagger-bootstrap-ui 访问权限控制&nbsp;<a href="https://blog.csdn.net/niugang0920/article/details/90229403">https://blog.csdn.net/niugang0920/article/details/90229403</a></p>
                                </div>

以上是关于Swagger使用的主要内容，如果未能解决你的问题，请参考以下文章

swagger文档转换为WebApiClient声明式代码

使用 Swashbuckle V5 从代码生成 swagger.json

Swagger-codegen 开始使用

Swagger 生成 Node.JS Express 服务器代码

Swagger结合mustache模板生成后台接口代码以及前后台建模代码

Swagger使用总结