Swagger——API文档生成

Swagger (丝袜哥) 是一个简单但是功能强大的API文档表述工具 。 就是通过 JSON , YAML 语言格式来生成及描述接口文档 ;
而 Spring 框架快速集成了Swagger, 也就是说,我们可以在spring项目中, 快速的通过swagger来生成接口文档 ;

使用方式
pom.xml

<?xml version="1.0" encoding="UTF-8"?>

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 + '\'' +
            '}';
}

}