微信公众号:一个优秀的废人
如有问题或建议,请后台留言,我会尽力解决你的问题。

前言

快过年了,不知道你们啥时候放年假,忙不忙。反正我是挺闲的,所以有时间写 blog。今天给你们带来 SpringBoot 集成 Swagger2 的教程。

什么是 Swagger2

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

为什么使用 Swagger2 ?

相信刚开始不熟悉 web 开发的时候,大家都有手写 Api 文档的时候。而手写 Api 文档主要有以下几个痛点:

文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。

接口返回结果不明确。

不能直接在线测试接口,通常需要使用工具,比如 postman。

接口文档太多,不好管理。

这些痛点在前后端分离的大型项目上显得尤为烦躁。而 Swagger2 的出现恰好能个解决这些痛点。因为 Swagger2 有以下功能:

文档自动更新,只要生成 Api 的网址没变,基本不需要跟前端沟通。

接口返回结果非常明确,包括数据类型,状态码,错误信息等。

可以直接在线测试文档,而且还有实例提供给你。

只需要一次配置便可使用,之后只要会有一份接口文档,非常易于管理。

集成演示

首先新建一个 SpringBoot 项目,还不会的参考我这篇旧文—— 如何使用 IDEA 构建 Spring Boot 工程

构建时,在选择依赖那一步勾选 Web、LomBok、JPA 和 Mysql 依赖。其中 Mysql 可以不勾,因为我这里用于操作实际的数据库,所以我勾选了。

生成 SpringBoot 后的 Pom 文件依赖如下:这里使用的是 2.4.0 的 Swagger2 版本。

<?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>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.1.2.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.nasus</groupId>
<artifactId>swagger2</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>swagger2</name>
<description>Demo project for Swagger2</description>
&lt;properties&gt;
&lt;java.version&gt;1.8&lt;/java.version&gt;
&lt;/properties&gt; &lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
&lt;artifactId&gt;spring-boot-starter-data-jpa&lt;/artifactId&gt;
&lt;/dependency&gt; &lt;dependency&gt;
&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
&lt;artifactId&gt;spring-boot-starter-web&lt;/artifactId&gt;
&lt;/dependency&gt; &lt;dependency&gt;
&lt;groupId&gt;mysql&lt;/groupId&gt;
&lt;artifactId&gt;mysql-connector-java&lt;/artifactId&gt;
&lt;scope&gt;runtime&lt;/scope&gt;
&lt;/dependency&gt; &lt;dependency&gt;
&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
&lt;artifactId&gt;spring-boot-starter-test&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt; &lt;dependency&gt;
&lt;groupId&gt;io.springfox&lt;/groupId&gt;
&lt;artifactId&gt;springfox-swagger2&lt;/artifactId&gt;
&lt;version&gt;2.4.0&lt;/version&gt;
&lt;/dependency&gt; &lt;dependency&gt;
&lt;groupId&gt;io.springfox&lt;/groupId&gt;
&lt;artifactId&gt;springfox-swagger-ui&lt;/artifactId&gt;
&lt;version&gt;2.4.0&lt;/version&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt; &lt;build&gt;
&lt;plugins&gt;
&lt;plugin&gt;
&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
&lt;artifactId&gt;spring-boot-maven-plugin&lt;/artifactId&gt;
&lt;/plugin&gt;
&lt;/plugins&gt;
&lt;/build&gt;

</project>

第二步,在 SpringBoot 启动类(Application)的同级目录新建一个 Swagger 配置类,注意 Swagger2 配置类必须与项目入口类 Application 位于同一级目录,否则生成 Api 文档失败,代码如下:

package com.nasus;

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; /**
  • Project Name:swagger2-demo <br/>
  • Package Name:com.nasus <br/>
  • Date:2019/1/22 22:52 <br/>
  • <b>Description:</b> TODO: 描述该类的作用 <br/>
  • @author <a href="[email protected]">nasus</a><br/>
  • Copyright Notice =========================================================
  • This file contains proprietary information of Eastcom Technologies Co. Ltd.
  • Copying or reproduction without prior written approval is prohibited.
  • Copyright (c) 2019 =======================================================

    */

    @Configuration

    // 启用 Swagger2

    @EnableSwagger2

    public class Swagger2 { @Bean

    public Docket createRestApi() {

    return new Docket(DocumentationType.SWAGGER_2)

    // 文档信息对象

    .apiInfo(apiInfo())

    .select()

    // 被注解的包路径

    .apis(RequestHandlerSelectors.basePackage("com.nasus.controller"))

    .paths(PathSelectors.any())

    .build();

    }

    private ApiInfo apiInfo() {

    return new ApiInfoBuilder()

    // 标题

    .title("springboot 利用 swagger 构建 API 文档")

    // Api 文档描述

    .description("简单优雅的 restful 风格,https://blog.csdn.net/turodog/")
             .termsOfServiceUrl("https://blog.csdn.net/turodog/")
    // 文档作者信息
    .contact(new Contact("陈志远", "https://github.com/turoDog", "[email protected]"))
    // 文档版本
    .version("1.0")
    .build();

    }

    }

第三步,配置被注解的 Controller 类,编写各个接口的请求参数,返回结果,接口描述等等,代码如下:

package com.nasus.controller;

import com.nasus.entity.Student;

import com.nasus.service.StudentService;

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiImplicitParam;

import io.swagger.annotations.ApiImplicitParams;

import io.swagger.annotations.ApiOperation;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.web.bind.annotation.DeleteMapping;

import org.springframework.web.bind.annotation.GetMapping;

import org.springframework.web.bind.annotation.PathVariable;

import org.springframework.web.bind.annotation.PostMapping;

import org.springframework.web.bind.annotation.PutMapping;

import org.springframework.web.bind.annotation.RequestBody;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RequestMethod;

import org.springframework.web.bind.annotation.RestController;

import springfox.documentation.annotations.ApiIgnore; /**
  • Project Name:swagger2-demo <br/>
  • Package Name:com.nasus.controller <br/>
  • Date:2019/1/22 22:07 <br/>
  • <b>Description:</b> TODO: 描述该类的作用 <br/>
  • @author <a href="[email protected]">nasus</a><br/>
  • Copyright Notice =========================================================
  • This file contains proprietary information of Eastcom Technologies Co. Ltd.
  • Copying or reproduction without prior written approval is prohibited.
  • Copyright (c) 2019 =======================================================

    */

    @RestController

    @RequestMapping("/student")

    // @Api:修饰整个类,描述Controller的作用

    @Api("StudentController Api 接口文档")

    public class StudentController { @Autowired

    private StudentService studentService; // @ApiOperation:描述一个类的一个方法,或者说一个接口

    @ApiOperation(value="获取所有学生列表", notes="获取所有学生列表")

    @RequestMapping(value={""}, method= RequestMethod.GET)

    public List<Student> getStudent() {

    List<Student> list = studentService.findAll();

    return list;

    } @ApiOperation(value="添加学生信息", notes="添加学生信息")

    // @ApiImplicitParam:一个请求参数

    @ApiImplicitParam(name = "student", value = "学生信息详细实体", required = true, dataType = "Student")

    @PostMapping("/save")

    public Student save(@RequestBody Student student){

    return studentService.save(student);

    } @ApiOperation(value="获学生信息", notes="根据url的id来获取学生详细信息")

    @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Integer",paramType = "path")

    @GetMapping("/{id}")

    public Student findById(@PathVariable("id") Integer id){

    return studentService.findById(id);

    } @ApiOperation(value="删除学生", notes="根据url的id来指定删除的学生")

    @ApiImplicitParam(name = "id", value = "学生ID", required = true, dataType = "Integer",paramType = "path")

    @DeleteMapping("/{id}")

    public String deleteById(@PathVariable("id") Integer id){

    studentService.delete(id);

    return "success";

    } @ApiOperation(value="更新学生信息", notes="根据url的id来指定更新学生信息")

    // @ApiImplicitParams:多个请求参数

    @ApiImplicitParams({

    @ApiImplicitParam(name = "id", value = "学生ID", required = true, dataType = "Integer",paramType = "path"),

    @ApiImplicitParam(name = "student", value = "学生实体student", required = true, dataType = "Student")

    })

    @PutMapping(value="/{id}")

    public String updateStudent(@PathVariable Integer id, @RequestBody Student student) {

    Student oldStudent = this.findById(id);

    oldStudent.setId(student.getId());

    oldStudent.setName(student.getName());

    oldStudent.setAge(student.getAge());

    studentService.save(oldStudent);

    return "success";

    } // 使用该注解忽略这个API

    @ApiIgnore

    @RequestMapping(value = "/hi", method = RequestMethod.GET)

    public String jsonTest() {

    return " hi you!";

    }

    }

第四步,启动项目,访问 http://localhost:8080/swagger-ui.html 地址,结果如下图:

项目源代码

github

图解接口

Swagger2 常用注解简介

@ApiOperation:用在方法上,说明方法的作用
1.value: 表示接口名称
2.notes: 表示接口详细描述
@ApiImplicitParams:用在方法上包含一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
1.paramType:参数位置
2.header 对应注解:@RequestHeader
3.query 对应注解:@RequestParam
4.path 对应注解: @PathVariable
5.body 对应注解: @RequestBody
6.name:参数名
7.dataType:参数类型
8.required:参数是否必须传
9.value:参数的描述
10.defaultValue:参数的默认值
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
1.code:状态码
2.message:返回自定义信息
3.response:抛出异常的类
@ApiIgnore: 表示该接口函数不对swagger2开放展示
@Api:修饰整个类,描述Controller的作用
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息

注意事项

@ApiImplicitParam 注解下的 paramType 属性,会影响接口的测试,如果设置的属性跟spring 的注解对应不上,会获取不到参数,例如 paramType=path ,函数内却使用@RequestParam 注解,这样,可能会获取不到传递进来的参数,需要按照上面进行对应,将 @RequestParam 注解改为 @PathVariable 才能获取到对应的参数。

后语

以上就是我对 Swagger2 的理解与使用,以上只是教大家入门 Swagger2 ,想要深入使用还是希望自行查阅官方文档。最后,对 Python 、Java 感兴趣请长按二维码关注一波,我会努力带给你们价值,如果觉得本文对你哪怕有一丁点帮助,请帮忙点好看,让更多人知道。

    <div class="fenyetiao"><pre>文章来源:segmentfault,作者:一个优秀的废人。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件至:william.shi#ucloud.cn(邮箱中#请改为@)进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容。</pre></div>

原文地址:https://www.cnblogs.com/java-zhao/p/5348113.html

04-14 02:25