整合Swagger-UI实现在线API文档

各位大佬好啊,我是你们的杨洋啊,今天跟大家聊聊(shui)一篇swagger-ui,嘿嘿,拖更了几篇,我会慢慢补上的…阅读前先点赞、养成好习惯呀~

Swagger-UI是什么?

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

为什么要使用Swagger-UI?

咱们程序员不喜欢虚的,肯定是直接列举跟日常工作学习相关的优点

动态地根据 注解
生成 在线API文档
,场景:

  1. 自测
    一般咱们写完新的功能接口都是要自测的,这时候肯定不能直接提交给前端的,之前没用swagger自测,使用postman等工具,还要写接口、写参数、设置请求头等等,接口少还好,写个十几个接口真要命,现在有了swagger就可以很便捷的调用测试自己接口了。

  2. 接口文档
    虽然在大部分公司都需要写接口文档,但是有时候需求真的很急的时候,来不及写接口文档,直接甩给前端这个swagger-ui页面,告诉他接口在哪,就是一片简化的 接口文档
    了,大大的 缩短了前后端的沟通

当然了,肯定还有很多别的好处,只是列举了两点最实用的

怎么使用Swagger-UI呢?

1.首先引入maven

<!--Swagger-UI API文档生产工具-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
复制代码

2.认识下swagger的常用注解

  • @Api:用于修饰Controller类,生成Controller相关文档信息
  • @ApiOperation:用于修饰Controller类中的方法,生成接口方法相关文档信息
  • @ApiParam:用于修饰接口中的参数,生成接口参数相关文档信息
  • @ApiModelProperty:用于修饰实体类的属性,当实体类是请求参数或返回结果时,直接生成相关文档信息

3.添加Swagger-UI的配置

此配置写demo可以不设置,写项目请设置一下

package com.yang.demo.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * swaggerApi文档配置
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为指定包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("com.yang.demo.controller"))
                //为有@Api注解的Controller生成API文档
                // .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
                // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerUI演示Demo")//页面标题
                .description("yangLeiDemo接口API")//描述
                .contact(new Contact("yanglei", "http://www.baidu.com", "13584019006@163.com"))//创建人及信息
                .version("1.0")//版本号
                .build();
    }


}

复制代码

4.在对应的类,方法上加上对应的注解

  • 类上@Api
  • 方法上@ApiOperation
@Api(tags = "MenuController", description = "菜单管理")
@RestController
@RequestMapping("/menu")
public class MenuController {

    private static final Logger LOG = LoggerFactory.getLogger(MenuController.class);

    @Resource
    private MenuService menuService;

    @ApiOperation(value = "获取所有的菜单", notes = "父节点为0的所有菜单信息")
    @GetMapping("/getMenuInfo")
    public List<MenuDto> getMenuInfo(){
        LOG.debug("MenuController");
        return menuService.getMenuInfo();
    }

}
复制代码
  • Dto上加上对应的信息
  • @ApiModel 用于修饰实体类
  • @ApiModelProperty 用于修饰实体类的成员变量
@ApiModel(value = "MenuDto", description = "菜单Model")
public class MenuDto {

    @ApiModelProperty(value = "菜单ID")
    private String menuCode;

    @ApiModelProperty(value = "菜单名称")
    private String menuName;

    @ApiModelProperty(value = "菜单父类ID")
    private String parentCode;

    @ApiModelProperty(value = "菜单链接")
    private String menuUrl;
复制代码

原文 

https://juejin.im/post/5f19a7256fb9a07ebf2b4eec

本站部分文章源于互联网,本着传播知识、有益学习和研究的目的进行的转载,为网友免费提供。如有著作权人或出版方提出异议,本站将立即删除。如果您对文章转载有任何疑问请告之我们,以便我们及时纠正。

PS:推荐一个微信公众号: askHarries 或者qq群:474807195,里面会分享一些资深架构师录制的视频录像:有Spring,MyBatis,Netty源码分析,高并发、高性能、分布式、微服务架构的原理,JVM性能优化这些成为架构师必备的知识体系。还能领取免费的学习资源,目前受益良多

转载请注明原文出处:Harries Blog™ » 整合Swagger-UI实现在线API文档

赞 (0)
分享到:更多 ()

评论 0

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址