Swagger的简单实用

Swagger

swagger是一款可以根据resutful风格生成接口开发文档，并且支持做测试的软件。

如何引入Swagger

在pom.xml中引入以下maven依赖：

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.7.0version>
dependency>
<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.7.0version>
dependency>

Swagger的常用注解

注解	说明
@Api	用在请求的类上，例如Controller，表示对类的说明
@ApiModel	用在类上，通常是实体类，表示一个返回响应数据的信息
@ApiModelProperty	用在属性上，描述响应类的属性
@ApiOperation	用在请求的方法上，说明方法的用途、作用
@ApiImplicitParams	用在请求的方法上，表示一组参数说明
@ApiImplicitParam	用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

如何使用

简单举个代码例子来说明下使用：
由于我们公司只允许使用POST方式请求，同时请求体只允许用实体类进行封装，所以部分Swagger注解不予记录。

首先定义两个实体类：

package com.example.swagger_demo.dto;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@Accessors(chain = true)
@ApiModel(description = "学生实体类")
public class StudentDTO {

    @ApiModelProperty(value = "姓名")
    private String name;

    @ApiModelProperty(value = "年龄")
    private Integer age;

    @ApiModelProperty(value = "性别")
    private Boolean sex;
    
}

package com.example.swagger_demo.dto;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@Accessors(chain = true)
@ApiModel(description = "书本实体类")
public class BookDTO {

    @ApiModelProperty(value = "姓名")
    private String name;

    @ApiModelProperty(value = "作者")
    private String author;

    @ApiModelProperty(value = "价格")
    private Double price;

}

@ApiModel和@ApiModelProperty分别对应下图：

然后再分别定义两个Controller，放在不同的包下：

package com.example.swagger_demo.controller.student;

import com.example.swagger_demo.dto.StudentDTO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/swagger")
@Api(tags = "学生接口组")
public class StudentController {

    @ApiOperation(value = "增加学生", notes = "增加学生信息")
    @PostMapping("/addStudent")
    public String addStudent(@RequestBody StudentDTO studentDTO) {
        return studentDTO.getName();
    }

    @ApiOperation(value = "查询学生", notes = "查询学生信息")
    @PostMapping("/queryStudent")
    public StudentDTO getStudent() {
        StudentDTO studentDTO = new StudentDTO();
        studentDTO.setAge(11).setName("aaa").setSex(true);
        return studentDTO;
    }

}

package com.example.swagger_demo.controller.book;

import com.example.swagger_demo.dto.BookDTO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/book")
@Api(tags = "书本接口组")
public class BookController {

    @ApiOperation(value = "增加书本", notes = "增加书本信息")
    @PostMapping("/addBook")
    public String addStudent(@RequestBody BookDTO bookDTO) {
        return bookDTO.getName();
    }

    @ApiOperation(value = "查询书本", notes = "查询书本信息")
    @PostMapping("/queryBook")
    public BookDTO getBook() {
        BookDTO bookDTO = new BookDTO();
        bookDTO.setName("西游记").setAuthor("吴承恩").setPrice(12.5);
        return bookDTO;
    }

}

最后定义SwaggerAutoConfiguration即可：

package com.example.swagger_demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;

@Configuration
@EnableSwagger2
public class SwaggerAutoConfiguration {

    @Bean
    public Docket createStudentRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).groupName("学生接口组")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger_demo.controller.student"))
                .build();
    }

    @Bean
    public Docket createBookRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).groupName("书本接口组")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger_demo.controller.book"))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            //页面标题
            .title("API接口文档")
            //创建人
            .contact(new Contact("转码厨子", "https://blog.csdn.net/qq_36583373?spm=1011.2415.3001.5343", ""))
            //版本号
            .version("1.0.0")
            //描述
            .description("API描述")
            .build();
    }

}

访问http://localhost:8080/swagger-ui.html即可访问。