Maven 项目集成 Swagger2

程序员飞飞

发布于 2020-02-27 09:36:15

3.8K00

代码可运行

文章被收录于专栏：Android&Java技术Android&Java技术

运行总次数：0

代码可运行

题图：来自飞哥的图片工厂

音乐推荐：背叛文丨IT大飞说预计阅读时间：3.2 分钟

哈喽，朋友们，今天我们来学习下如何使用 Swagger2。

什么是 Swagger?

Swagger 是一款 RESTFUL 接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。

如何集成？

打开 pom.xml 文件，添加如下依赖：

<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.9.2，当你看到这篇文章的时候可能会有更新，最新的版本可到 https://mvnrepository.com 查看。

新建一个 Swagger2 类，完整代码如下：

@Configuration
@EnableSwagger2 // 启用 Swagger
@EnableWebMvc
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.xpf.imoney"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 构建 api 文档的详细信息函数，注意这里的注解引用的是哪个
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("SSM Application [iMoney] Swagger2 RESTFul API")
                // 创建人
                .contact(new Contact("x-sir", "http://www.x-sir.com", "542270559@qq.com"))
                // 版本号
                .version("1.0")
                // 描述
                .description("This is [iMoney] API doc")
                .build();
    }
}

然后编译并启动你本地的服务，打开浏览器，输入下面的访问地址：

http://localhost:8080/JavaWeb/swagger-ui.html

注：上面链接中的 JavaWeb 为你的项目名称，替换为你自己的！

正常情况下你就会看到下面的页面了：

Swagger 的几个常用注解

@Api：表示这个类是 Swagger 的资源；
@ApiOperation：用在方法上，说明方法的作用；
@ApiParam：用来修饰参数，表示对参数添加元数据；
@ApiModel：用于类，对类进行说明；
@ApiIgnore：用于类，方法，表示这个类或方法被忽略；
@ApiImplicitParam：用于方法，表示单独的请求参数；

举个例子，我们的 UserController 中的简单使用，完整代码如下：

@Api(value = "/user", description = "关于用户的一些操做。")
@Controller
public class UserController {

    @Resource
    private UserService userService;

    @ResponseBody
    @RequestMapping(value = "/index")
    @ApiOperation(value = "通过 ID 查询 USER 信息", httpMethod = "GET", notes = "暂无")
    public User index(@RequestParam("id") int id) {
        return userService.getUserById(id);
    }
}