原创

SpringBoot项目实战（9）：整合swagger2

温馨提示：
本文最后更新于 2017年10月13日，已超过 2,598 天没有更新。若文章内的图片失效（无法正常加载），请留言反馈或直接联系我。

前言

swagger Restful文档生成工具 2017-9-30

官方地址：https://swagger.io/docs/specification/about/

官方Github：https://github.com/swagger-api/swagger-core/wiki/Annotations

启动项目，访问http://localhost:8082/swagger-ui.html查看API

注意，此项目示例中，使用了三种ui依赖，每种依赖对应的访问页面不同：

springfox-swagger-ui -> http://localhost:8082/swagger-ui.html

swagger-bootstrap-ui -> http://localhost:8082/doc.html 

swagger-ui-layer -> http://localhost:8082/docs.html

使用方法

1.添加依赖（springfox-swagger2依赖是必须的，三种ui依赖只需要使用一个就行）

<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>

2.创建配置文件Swagger2Config.java

@EnableSwagger2
@Configuration
public class Swagger2Config {

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

    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
                .termsOfServiceUrl("http://localhost/")
                //创建人
                .contact("zhyd")
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

注：@EnableSwagger2注解一定不要漏掉

3.编写文档

@RestController
@RequestMapping("/demo")
@Api(value = "测试Swagger2",description="简单的API")
public class UserController {

    @ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "java.lang.Long", name = "id", value = "id", required = true, paramType = "path"),
            @ApiImplicitParam(dataType = "User", name = "user", value = "用户信息", required = true)
    })
    @ApiResponses({
            @ApiResponse(code = 500, message = "接口异常"),
    })
    @RequestMapping(value = "/user/{id}", method = RequestMethod.POST)
    public User insert(@PathVariable Long id, @RequestBody User user) {

        System.out.println("id:" + id + ", user:" + user);
        user.setId(id);

        return user;
    }
}

注意：如果api文档只是针对开发人员使用的，就需要后台对v2/api-docs路径进行过滤，对非开发人员应该是不可见的。

自定义api页面

本例是使用的swagger-ui-layer主题（链接请见本文最后）。使用自定义api页面就不需要在pom中配置ui依赖了，详情查看static目录

api页面访问地址：http://localhost:8082/api.html

页面效果参考

swagger-ui.html


bootstrap-ui.html


layer-ui.html.html


layer-ui-custom.html


参考链接

swagger-ui-layer地址：https://github.com/caspar-chen/swagger-ui-layer

Swagger-Bootstrap-UI地址：https://github.com/xiaoymin/Swagger-Bootstrap-UI

git源码：https://github.com/zhangyd-c/springboot/tree/master/springboot-swagger

其他相关文章


正文到此结束
所属分类：后端编程
热门推荐
相关文章
关于我
微信公众号
张亚东博客
一个程序员的个人博客，心之所向，无所不能
本文目录
    标签云
    Linux Java Spring Spring Boot Maven Docker IDE uzip war Shell Flyat chrome 自动化测试 Git Task 爬虫 MySQL JS 正则 Tomcat FindBugs 版本控制 Nginx Apache 其他 阿里云优惠券 微信小程序 网易云音乐 阿里云服务器 阿里云优惠活动 ztree Cordova Android 开源 第三方登录 安全 websocket OneBlog 码一码 微信 yuicompressor 博客迁移 开源 hunter 开源软件 JustAuth
    近期评论
    网站信息
    • 文章总数：148 篇
    • 标签总数：46 个
    • 分类总数：11 个
    • 留言数量：964 条
    • 在线人数：1人
    • 运行天数：3,086天
    • 最后更新：2021年08月13日17点
    • 系统版本：v2.3.4