一、Swagger2

  • 一个测试API和生成OpenAPI的Web服务
  • 一个强大的接口管理工具,提供了多种编程语言的前后端分离解决方案
  • 通过特定的注解直接整合到代码中,自动生成API文档
  • 界面简洁清晰可在线运行接口结果可直接导入到本地

二、Swagger2常用注解

转自 weixin_39477597

  • 作用在类上
    • @Api() 表明该类是swagger的资源
      • 参数tags: 说明类作用
  • 作用在方法上
    • @ApiOperation() 说明该方法的作用
      • 参数value: 方法作用
      • 参数notes: 备注说明
    • @ApiImplicitParam() 指定一个请求参数的信息
      • 参数name: 参数名
      • 参数value: 参数的说明
      • 参数required: 参数是否是必须的
      • 参数dataType: 参数类型
      • 参数defaultValue: 参数的默认值
    • @ApiImplicitParams() 表示一组参数说明,里面包含多个@ApiImplicitParam()
    • @ApiResponse() 表示一个错误的响应信息
      • 参数code: http状态码
      • 参数message: 信息
      • 参数response: 抛出的异常类
    • @ApiResponses() 表示一组响应说明,里面包含多个@ApiResponse()
    • @ApiModel() 作用在响应类上,表示一个返回响应数据的信息
    • @ApiModelProperty() 作用在属性上,描述响应类的属性

三、构建项目

1、导入依赖

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<!-- web依赖 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- mysql依赖 -->
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
</dependency>
<!-- mybatis依赖 -->
<dependency>
<groupId>org.mybatis.spring.boot</groupId>
<artifactId>mybatis-spring-boot-starter</artifactId>
<version>1.3.1</version>
</dependency>
<!-- swagger2依赖 -->
<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>

2、创建Swagger配置类

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}

/**
* title() 页面标题
* contact(new Contact(name,email)) 创建人
* version() 项目版本
* description() 项目描述
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot整合Swagger2构建RESTFUL API !!!")
.contact(new Contact("RONALDO", "http://www.cronaldo7.com", "a1781884292@163.com"))
.version("1.0")
.description("测试项目")
.build();
}
}

3、创建Mybatis配置类

1
2
3
4
5
6
7
8
9
10
11
12
13
@Configuration
public class MybatisConfig {
@Bean
public ConfigurationCustomizer configurationCustomizer() {
return new ConfigurationCustomizer() {
@Override
public void customize(org.apache.ibatis.session.Configuration configuration) {
// 设置驼峰命名规则
configuration.setMapUnderscoreToCamelCase(true);
}
};
}
}

4、创建实体

1
2
3
4
5
6
@Data
public class Book implements Serializable {
private int id;
private String name;
private float price;
}

5、创建mapper

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@Mapper
public interface BookMapper {

@Insert({"insert into book(id, name, price) values(#{id}, #{name}, #{price})"})
void addBook(Book book);

@Delete("delete from book where id=#{id}")
void delBookById(@Param("id") int id);

@Update("update book set name = #{name}, price = #{price} where id = #{id}")
void updateBookById(@Param("name") String name, @Param("price") float price, @Param("id") int id);

@Select("select * from book")
List<Book> getBook();
}

6、创建service及实现

1
2
3
4
5
6
7
8
9
10
public interface BookService {

void addBook(Book book);

void delBookById(int id);

void updateBookById(Book book);

List<Book> getBook();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
@Service
public class BookServiceImpl implements BookService {

@Autowired
private BookMapper bookMapper;

@Override
public void addBook(Book book) {
bookMapper.addBook(book);
}

@Override
public void delBookById(int id) {
bookMapper.delBookById(id);
}

@Override
public void updateBookById(Book book) {
bookMapper.updateBookById(book.getName(),book.getPrice(),book.getId());
}

@Override
public List<Book> getBook() {
return bookMapper.getBook();
}
}

7、创建控制层

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
@RestController
@RequestMapping("/api")
@Api(tags = "图书类相关API")
public class IndexController {

@Autowired
private BookService bookService;

@ApiOperation(value = "查询所有图书")
@RequestMapping(value = "/book", method = RequestMethod.GET)
public List<Book> query() {
return bookService.getBook();
}

@ApiOperation("新增图书信息")
@RequestMapping(value = "/book", method = RequestMethod.POST)
public void save(Book book) {
bookService.addBook(book);
}

@ApiOperation("修改图书信息")
@RequestMapping(value = "/book", method = RequestMethod.PUT)
public void modify(Book book) {
bookService.updateBookById(book);
}

@ApiOperation("删除图书信息")
@ApiImplicitParam(name = "id", value = "书本编号", required = true, dataType = "Integer")
@ApiResponses({
@ApiResponse(code = 400, message = "请求参数缺少"),
@ApiResponse(code = 404, message = "请求路径没找到")
})
@RequestMapping(value = "/book", method = RequestMethod.DELETE)
public void delete(@RequestParam(value = "id") int id) {
bookService.delBookById(id);
}
}

四、使用Swagger2对API进行测试