Maven 项目集成 Swagger2

程序员飞飞

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

3.7K0

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

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

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

音乐推荐：背叛文丨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);
    }
}

基本的用法就这些，好了，今天的分享就到这里了。

最后，我这边有个技术交流群，平常我会分享一些学习资源到群里，还可以和大家一起交流学习，需要的朋友可以扫描下面的二维码加我微信并备注「加群」，拉你进入技术交流群！

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2019/07/13 ，如有侵权请联系 cloudcommunity@tencent.com 删除

java

api

本文分享自作者个人站点/博客前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

java

api

登录后参与评论

0 条评论

热度