美化一下你的API文档吧(springboot集成swagger及遇到的问题)

微服务的流行提供了诸多的方便,随着也带来了N多的API,而swagger2正是一个对API管理的很好的“工具”,本文主要介绍springboot对swagger2的集成,以及集成中遇到的无法访问的问题。

1、pom添加依赖

      <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
        </dependency>

2、配置swagger的基本信息

创建SwaggerConfig ,内容如下:

package com.mos.eboot.service.config;

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;

/**
 * @author 小尘哥
 * api 地址:http://localhost:9090/swagger-ui.html
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mos.eboot.service"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("eboot-api文档")
                .description("更多信息,请访问https://www.jianshu.com/u/3979cb11f079")
                .termsOfServiceUrl("https://gitee.com/QuanZhanZhiLu/easy-boot")
                .version("1.0")
                .build();
    }
}

3、swagger的使用

举个栗子:

    @ApiOperation(value = "获取菜单详情",notes = "根据id获取菜单")
    @ApiImplicitParam(name = "id", value = "菜单ID", required = true, dataType = "String", paramType = "query")
    @RequestMapping("get-by-id")
    public ResultModel<SysMenu> getById(@RequestParam("id") String id) {
        SysMenu menu = menuService.selectById(id);
        menu.setParentNode(menuService.selectById(menu.getParentId()));
        return new ResultModel<>(ResultStatus.SUCCESS, menu);
    }

    @ApiOperation(value = "删除菜单",notes = "根据id删除菜单")
    @ApiImplicitParam(name = "id", value = "菜单ID", required = true, dataType = "String", paramType = "query")
    @PostMapping("del-by-id")
    public ResultModel<String> delById(@RequestParam("id") String id) {
        return this.basicResult(menuService.deleteById(id));
    }

4、查看ui界面

访问:http://[ip]:[端口]/swagger-ui.html

404.png

惊不惊喜?意不意外?

5、原因

出了bug当然有解决方案,为什么会出现这问题呢?因为springboot默认的静态资源在static下面,而我们看一下swagger-ui.html的目录结构如下图

swagger

看到这里基本都明白怎么回事儿了,我们只需要重写静态资源的路径即可

6、解决方案

  @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/META-INF/resources/").setCachePeriod(0);
    }

7、API界面

主界面

8、以menu-controller为例

3.png

大家会发现一个问题,“删除菜单”的api只有一个,而“获取菜单”的api则有7个之多,可是代码中我们明明只有一个方法,为什么呢?对,就是@RequestMapping和@PostMapping的区别,这也提醒我们尽可能写代码的时候要规范,一个api只接受一种的请求方式,不能为了方便让后面乱了套了。

点击https://gitee.com/QuanZhanZhiLu/easy-boot获取源码

原文发布于微信公众号 - 陌与尘埃(grq100296)

原文发表时间:2018-05-28

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏IT笔记

SpringBoot开发案例之整合Swagger篇

前段时间整合过的一个支付服务,由于使用了Spring Boot快速开发,但是又懒得写详细的文档介绍,便顺手就把Swagger整合进来了,对支付服务进行分组API...

2847
来自专栏我的博客

ubuntu配置虚拟主机[单ip多网站]

第一修改apache配置文件 /etc/apache2/sites-available 下面的default文件 在文件最后加上 <VirtualHos...

3605
来自专栏xingoo, 一个梦想做发明家的程序员

Linux下Apache服务器使用入门----.htaccess

这个文件的作用就是,把它放在某个目录下面,它所修改的配置方案会应用到这个目录,及其子目录 开启方式: 在/etc/httpd/conf/httpd.conf文件...

2038
来自专栏Albert陈凯

2018-11-18 swagger2 自动生成API

作者:小莫 链接:https://www.zhihu.com/question/28119576/answer/134580038 来源:知乎 著作权归作...

2473
来自专栏carven

实习笔记2--20160121

860
来自专栏JMCui

SpringMVC 中配置 Swagger 插件.

一、简介  Swagger的目标是为REST API定义一个与语言无关的标准接口,允许用户发现和理解计算机服务的功能,而无需访问源代码。当通过Swagger正确...

4864
来自专栏xingoo, 一个梦想做发明家的程序员

Apache虚拟主机-解惑篇

    有很多平时喜欢钻研的童鞋会发现,为什么有时候自己访问某XXse网站时,总是更新IP地址,内容却与以前一样。这个时候就要了解虚拟主机的概念了。了解这个概...

2995
来自专栏battcn

一起来学SpringBoot | 第十一篇:集成Swagger在线调试

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

1073
来自专栏xingoo, 一个梦想做发明家的程序员

Elasticsearch+Logstash+Kibana教程

参考资料 累了就听会歌吧! Elasticsearch中文参考文档 Elasticsearch官方文档 Elasticsearch 其他——那些年遇到的坑 El...

4807
来自专栏狂码一生

linux服务器Apache绑定多个域名

一、配置httpd.conf   vim /etc/etc/httpd/conf/httpd.conf   1、将 ServerName www.example...

4929

扫码关注云+社区

领取腾讯云代金券