Swagger (丝袜哥) 是一个简单但是功能强大的API文档表述工具 。 就是通过 JSON , YAML 语言格式来生成及描述接口文档 ;
而 Spring 框架快速集成了Swagger, 也就是说,我们可以在spring项目中, 快速的通过swagger来生成接口文档 ;
使用方式
pom.xml
4.0.0
<groupId>com.tensquare</groupId>
<artifactId>tensquare_swagger_demo</artifactId>
<version>1.0-SNAPSHOT</version>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.1.4.RELEASE</version>
</parent>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<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>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.21</version>
</dependency>
</dependencies>
application.yml
springfox.documentation.swagger.v2.path: /api-docs
启动类
package cn.itcast;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class,args);
}
}
controller
package cn.itcast.controller;
import cn.itcast.domain.Student;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;
@RestController
@RequestMapping("/student")
@Api(tags = “学生管理接口”)
public class StudentApi {
@GetMapping("/{id}")
@ApiOperation(value = "根据id查询学生信息")
public Student findById(@ApiParam(value = "学生id", required = true) @PathVariable Integer id) {
Student student = new Student();
student.setId(1);
student.setGender("1");
student.setName("Tom");
return student;
}
@GetMapping
@ApiOperation(value = "查询所有的学生信息")
public List<Student> findAll() {
List<Student> stuList = new ArrayList<Student>();
Student student = new Student();
student.setId(1);
student.setGender("1");
student.setName("Tom");
stuList.add(student);
return stuList;
}
@PutMapping
@ApiOperation(value = "添加学生信息")
public void add() {
}
@PostMapping
@ApiOperation(value = "修改学生信息")
public void update(@ApiParam(value = "学生信息", required = true) Student student) {
}
@DeleteMapping("/{id}")
@ApiOperation(value = "删除学生信息")
public void delete(@ApiParam(value = "学生id", required = true) @PathVariable Integer id) {
}
@GetMapping("/get/{id}")
@ApiOperation(value = "根据ID获取学生信息")
public void getById(@ApiParam(value = "学生id22222222", required = true) @PathVariable Integer id) {
}
}
config
package cn.itcast.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title(“十次方 API 文档”)
.description(“十次方 API 文档!!!”)
.version(“1.0.0”)
.build();
}
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// spring controller 包位置
.apis(RequestHandlerSelectors.basePackage("cn.itcast.controller"))
.paths(PathSelectors.any())
.build();
}
}
实体类
package cn.itcast.domain;
import io.swagger.annotations.ApiModelProperty;
public class Student {
@ApiModelProperty("学生id")
private Integer id;
@ApiModelProperty("学生姓名")
private String name;
@ApiModelProperty("学生性别")
private String gender;
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getGender() {
return gender;
}
public void setGender(String gender) {
this.gender = gender;
}
@Override
public String toString() {
return "Student{" +
"id=" + id +
", name='" + name + '\'' +
", gender='" + gender + '\'' +
'}';
}
}