Spring Boot 项目实战（三）集成 Swagger 及 JavaMelody

一、前言

上篇介绍了 Logback 的集成过程，总体已经达到了基本可用的项目结构。本篇主要介绍两个常用工具，接口文档工具 Swagger 、项目监控工具 JavaMelody 的集成步骤。

---

二、Swagger

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染变成了前端渲染、前后端分离的形态。前后端唯一的联系变成了 API 接口，API 文档成了前后端开发人员联系的纽带，Swagger 就是一款让我们更好书写 API 文档的框架。

2.1 为什么要用 Swagger

在日常开发过程中，有一个问题始终困扰着我们，那就是接口文档的可靠性。想必我们都经历过接口变动但接口文档没更新的窘境。单独维护接口文档不仅费时费力，而且会经常遗漏。Swagger 通过在接口及实体上添加几个注解的方式就能在项目启动后自动生成接口文档，尽管这样会带来一定的代码侵入性，但与其带来的好处相比就微不足道了。

2.2 集成 Swagger

① 首先在项目父 pom 文件中定义 Swagger 的版本号且声明 Swagger 依赖。

<properties>
    ...省略其余部分...
    <swagger.version>2.8.0</swagger.version>
</properties>

<dependencyManagement>
    <dependencies>
        ...省略其余部分...
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
    </dependencies>
</dependencyManagement>

② 其次在 demo-web 层中的 pom 文件中添加上述依赖

<dependencies>
    ...省略其余部分...
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
    </dependency>
</dependencies>

③ 然后在 com.example.demo.web 包中添加 config 目录并新建 Swagger 配置文件，具体内容如下：

package com.example.demo.web.config;

import org.springframework.beans.factory.annotation.Value;
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;

/**
 * @author linjian
 * @date 2019/2/2
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value(value = "${swagger.enabled}")
    private Boolean swaggerEnabled;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(swaggerEnabled)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.web.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("Spring Boot 集成 Swagger")
                .termsOfServiceUrl("https://symonlin.github.io")
                .version("1.0")
                .build();
    }
}

其中 「 swaggerEnabled 」表示是否开启 Swagger，一般线上环境是关闭的，所以可在 application.properties 文件中设置配置项。「 apis 」设置了 controller 的包路径。

④ 随后在先前创建的 DemoController 中添加 Swagger 的相关注解。

package com.example.demo.web.controller;

import com.example.demo.biz.service.DemoService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author linjian
 * @date 2019/1/15
 */
@Api(tags = "demo")
@RestController
@RequestMapping("demo")
public class DemoController {

    @Autowired
    private DemoService demoService;

    @GetMapping("test")
    @ApiOperation("测试")
    public String test() {
        return demoService.test();
    }
}

⑤ 最后启动项目，访问 http://localhost:8080/swagger-ui.html 测试 Swagger。

⑥ 使用 Swagger UI 测试 test 接口，点击「 Try it out 」>> 「 Execute 」

2.3 Swagger 常用注解说明

注解	说明	使用位置
@Api	描述 controller 的作用	用于 controller 类上
@ApiOperation	描述 controller 方法的作用	用于 controller 方法上
@ApiParam	描述 controller 方法参数的作用	用于 controller 方法的参数上
@ApiModel	描述对象的作用	用于请求对象或者返回结果对象上
@ApiModelProperty	描述对象里字段的作用	用于请求对象或者返回结果对象里的字段上

注：其余注解大家可自行查阅文档

---

三、JavaMelody

3.1 JavaMelody 介绍

JavaMelody 是用来在 QA 和实际运行生产环境中监控 Java 或 Java EE 应用程序服务器的一个开源框架。它不是一个工具来模拟来自用户的请求，而是一个测量和计算用户在实际操作中应用程序的使用情况的工具，并以图表的形式显示，图表可以按天，周，月，年或自定义时间段查看。

3.2 集成 JavaMelody

① 首先在项目父 pom 文件中声明 JavaMelody 依赖

<dependency>
    <groupId>net.bull.javamelody</groupId>
    <artifactId>javamelody-spring-boot-starter</artifactId>
    <version>1.74.0</version>
</dependency>

② 其次在 demo-web 层中的 pom 文件中添加上述依赖

<dependencies>
    ...省略其余部分...
    <dependency>
        <groupId>net.bull.javamelody</groupId>
        <artifactId>javamelody-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

③ 最后启动项目，访问 http://localhost:8080/monitoring 查看

④ 为了加强安全性，修改默认访问地址以及设置为登录后才可访问，可在 application.properties 文件中添加以下配置项

javamelody.init-parameters.authorized-users = admin:pwd
javamelody.init-parameters.monitoring-path = /demo/monitoring

---

四、结语

至此，Swagger 及 JavaMelody 的集成步骤已介绍完毕。