Spring Boot&Swagger构建REST API并生成API文档

分手后的思念是犯贱 2022-05-26 12:16 212阅读 0赞

什么是Swagger？

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。

前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要， Swagger就是一款让你更好的书写API文档的框架。

Swagger的优点？

官方说法： Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

不难看出， Swagger的一个最大的优点是能实时同步api与文档。

· 引入Maven依赖

<parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.8.RELEASE</version>
        <relativePath/>
    </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.2.2</version>
            </dependency>
        <dependency>
           	<groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>
    </dependencies>

· 创建Application主类

package nextdms;//注意包结构 
        @SpringBootApplication 
        public class Application { 
        public static void main(String[] args) throws Exception {
            SpringApplication.run(Application.class, args); 
        } 
    }

· 在启动application的相同目录下创建Swagger配置类

package nextdms;//注意包结构 
    @Configuration
    @EnableSwagger2
    public class Swagger2Configuration {
        @Bean
        public Docket buildDocket() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(buildApiInf())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.nextdms.crm.controller"))//要扫描的API(Controller)基础包	    
                    .paths(PathSelectors.any())
                    .build();
        }
        private ApiInfo buildApiInf() {
            return new ApiInfoBuilder()
                    .title("Spring Boot中使用Swagger2 UI构建API文档")
                    .contact("土豆")
                    .version("1.0")
                    .build();
        }
    }

· 创建RestController 构建一个简单计算服务API

package nextdms.controller.logis.inven;//注意包结构
    
    @Api(value = "计算服务",description="简单的计算服务，提供加减乘除运算API")
    @RestController
    @RequestMapping("/compute")
    public class ComputeController {
          @ApiOperation("加法运算")
          @PostMapping("/add")
          public Double add(@RequestParam Double a,  @RequestParam Double b) {
             return a + b;
          }
       
          @ApiOperation("减法运算")
          @PostMapping("/sub")
          public Double sub(@RequestParam Double a,  @RequestParam Double b) {
              return a - b;
          }
    
          @ApiOperation("乘法运算")
          @PostMapping("/mul")
          public Double mul(@RequestParam Double a,  @RequestParam Double b) {
              return a * b;
          }
    
          @ApiOperation("除法运算")
          @PostMapping("/div")
          public Double div(@ApiParam("被除数")@RequestParam Double a, @ApiParam("除数")@RequestParam   Double b) {
              return a / b;
          }
    }

注：

@Api注解用来表述该服务的信息，如果不使用则显示类名称.

@ApiOperation注解用于表述接口信息

@ApiParam注解用于描述接口的参数

在GET请求中，使用@RequestParam注解来接受Http请求参数。

在POST请求，可使用@RequestBody和@RequestParam。

通过上面几步我们已经成功构建了一个具备加减乘除的计算服务API，并且已经拥有一份不错的在线文档了，现在我们来启动它，执行mvn spring-boot:run，或直接运行Application.main()。

启动成功后，访问 [http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html]，便可以看到我们刚才构建的计算服务的API文档了。（注意：端口号可能不一样）

效果如下： ![20180502114414343][]

Swagger UI不仅仅是文档，还提供了在线API调试的功能，我们可以调试下我们的除法运算API。

![20180502114444997][]

点击Try it out！后可以看到我们成功的调用了除法运算API并获得了正确的响应。

![2018050211450191][]

本示例完整代码的GIT地址 [点击我~][Link 1]

Swagger-Core文档 [点击我~][Link 2]

SpringFox文档 [点击我~][Link 3]

Spring Boot 文档 [点击我~][Link 4]

更多相关注解 [点击我~][Link 5]

作者：简单的土豆

链接：https://www.jianshu.com/p/c5cb33ad4305

來源：简书

著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。

**一个从装环境开始的学习记录公众号，欢迎大家关注：**

![20200618140202867.jpg][]

[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[20180502114414343]: /images/20220526/38a2fe1bd6244ccbbb30e7c732dd528d.png
[20180502114444997]: /images/20220526/95ea40a7f22b4102a552572b6fa4ba74.png
[2018050211450191]: /images/20220526/0ee21c143bac44fda6a879b4fdeb4796.png
[Link 1]: https://link.jianshu.com/?t=https://github.com/lihengming/spring-boot-swagger-example
[Link 2]: https://link.jianshu.com/?t=https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-JAX-RS-Project-Setup-1.5.X
[Link 3]: https://link.jianshu.com/?t=http://springfox.github.io/springfox/
[Link 4]: https://link.jianshu.com/?t=http://docs.spring.io/spring-boot/docs/1.5.0.BUILD-SNAPSHOT/reference/htmlsingle/
[Link 5]: https://link.jianshu.com/?t=https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#quick-annotation-overview
[20200618140202867.jpg]: /images/20220526/e8827466bf4941ca9a303da56e674dd8.png