前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >美化一下你的API文档吧(springboot集成swagger及遇到的问题)

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

作者头像
小尘哥
发布2018-08-15 10:39:45
1.6K0
发布2018-08-15 10:39:45
举报
文章被收录于专栏:小尘哥的专栏小尘哥的专栏

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

1、pom添加依赖

代码语言:javascript
复制
      <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
        </dependency>

2、配置swagger的基本信息

创建SwaggerConfig ,内容如下:

代码语言:javascript
复制
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的使用

举个栗子:

代码语言:javascript
复制
    @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、解决方案

代码语言:javascript
复制
  @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获取源码

本文参与 腾讯云自媒体同步曝光计划,分享自微信公众号。
原始发表:2018-05-28,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 陌与尘埃 微信公众号,前往查看

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

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

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 1、pom添加依赖
  • 2、配置swagger的基本信息
  • 3、swagger的使用
  • 4、查看ui界面
  • 5、原因
  • 6、解决方案
  • 7、API界面
  • 8、以menu-controller为例
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档