前言
工作中难免会遇到写文档，特别是在大型项目中，接口文档的编写一直是一个令人头疼的问题，开发人员会花费大量的时间去写接口文档。今天推荐一款自动生成接口的工具----Swagger ,它大大的节约了开发人员的写文档的时间，最重要的是，它还支持在线接口测试，Swagger官网为https://swagger.io/。
一、Swagger 常用注解
@Api()用于类；
表示标识这个类是swagger的资源
@ApiOperation()用于方法；
表示一个http请求的操作
@ApiParam()用于方法，参数，字段说明；
表示对参数的添加元数据（说明或是否必填等）
@ApiModel()用于类
表示对类进行说明，用于参数用实体类接收
@ApiModelProperty()用于方法，字段
表示对model属性的说明或者数据操作更改
@ApiIgnore()用于类，方法，方法参数
表示这个方法或者类被忽略
@ApiImplicitParam() 用于方法
表示单独的请求参数
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
二、如何使用Swagger？
（一） 开发工具
JDK1.8
Apache Maven 3.5.0
IntelliJ IDEA 2018.2.5
（二）引入依赖
<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>
（三）配置Swagger
package com.example.demo.swagger.config;
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;
/**
* @Author: Jackieonway
* @Description: Swagger 配置类
* @Version: 1.0
*/
@EnableSwagger2
@Configuration
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//Controller所在包(必须新建包)
.apis(RequestHandlerSelectors.basePackage("com.example.demo.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//接口文档的名字
.title("demo api")
//接口文档的描述
.description("demo api接口文档")
//服务条款网址
.termsOfServiceUrl("http://localhost/")
//接口文档的版本
.version("1.0.0")
// 接口文档维护联系信息
.contact(new Contact("Jakieonway", "", "jackieonway@outlook.com"))
.build();
}
}
（四） 使用Swagger
参数Model使用
package com.example.demo.swagger.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* @author Jackieonwaya
* @version 1.0
**/
@ApiModel("示例实体") //参数Model对应的接口文档
public class Demo {
@ApiModelProperty("名字") //参数Model对应属性的接口文档描述
private String name;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
@Override
public String toString() {
final StringBuilder sb = new StringBuilder("{");
sb.append("\"name\":\"")
.append(name).append('\"');
sb.append("}");
return sb.toString();
}
}
测试Controller
package com.example.demo.swagger.controller;
import com.example.demo.swagger.entity.Demo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @author Jackieonway
* @version 1.0
**/
// 用于类；表示标识这个类是swagger的资源
//tags:说明，如果有多个tags,则会以list形式展示
//value: 说明，可以使用tags替代
@Api(value = "测试Controller" , tags = "测试类")
@RestController
public class TestController {
//用于方法；表示一个http请求的操作
//value: 用于方法描述
//notes: 用于提示内容
//tags: 可以重新分组
@ApiOperation(value = "测试方法")
@GetMapping("/get")
//用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
//name:参数名
//value:参数说明
//required:是否必填
public String get(@ApiParam(name = "姓名",value = "姓名值",required = true) String name){
return "Swagger 测试 返回值 : " + name;
}
@ApiOperation(value = "测试返回方法",notes = "必传参数: name")
@GetMapping("/getDemo")
public Demo getDemo(Demo demo){
return demo;
}
}
使用效果
访问 http://localhost:8080/swagger-ui.html
Swagger界面
swagger-ui.png
Swagger 展示内容
image.png
以多个参数形式接收，如果设置@ApiParam 的required = true则会显示required
image.png
以对象接收
image.png
小结
通过以上的配置和使用，Swagger在Spring Boot中已经成功完成。接下来就看小伙伴在项目中的实际使用吧。更多关于Swagger的用法，请参考官方使用文档。
附完整的Pom文件
<?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>
<groupId>com.example</groupId>
<artifactId>demo-swagger</artifactId>
<version>0.0.1-SNAPSHOT</version>
<packaging>jar</packaging>
<name>demo-swagger</name>
<description>Demo project for Spring Boot</description>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.1.0.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<!-- 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>
<!-- Swagger 配置结束 -->
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
网友评论