swagger文档生成与查看-业务模块-Saas多租户平台开发

其他 2021-01-29 23:44:59 阅读次数: 0

swagger文档生成与查看-业务模块-Saas多租户平台开发

目录

文章目录



内容

本文只是简述swagger2如何生成文档过程，关于swagger2详细教程以及源码之类的可自行查阅相关文档。

1、API 文档

现在项目基本上都是前后端分离模式，而且前后端分别由不同的团队开发，那么前后端开发人员的交流就变得很关键。选择好的交流方式，提高开发效率；反之，影响项目进度。
同为技术人员，写API文档成为很好的交互方案。swagger2模块，通过简单添加注解，就可以自动生成API文档。

2、swagger2生成API文档

  • swagger2生成API步骤：
  1. 引入依赖
    • springfox-swagger2
    • springfox-swagger-ui
  2. 创建swagger配置类
    • 说明：

      • @EnableSwagger2注解是必须的

      • 其他信息根据需要配置

          package com.ihrm.common.config;

  import io.swagger.annotations.ApiOperation;
  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;
  import springfox.documentation.swagger2.annotations.EnableSwagger2;

  /**
   * Swagger配置
   */
  @Configuration
  @EnableSwagger2
  public class SwaggerConfig {

  	@Bean
  	public Docket createRestApi() {
  		return new Docket(DocumentationType.SWAGGER_2)
  			.apiInfo(apiInfo())
  			.select()
  			//加了ApiOperation注解的类，生成接口文档
  			.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
  			//包下的类，生成接口文档
  			//.apis(RequestHandlerSelectors.basePackage("io.renren.modules.job.controller"))
  			.paths(PathSelectors.any())
  			.build();
  	}

  	private ApiInfo apiInfo() {
  		return new ApiInfoBuilder()
  			.title("ihrm开源")
  			.description("ihrm-company文档")
  			.termsOfServiceUrl("https://www.gaogzhen.com")
  			.version("4.0.0")
  			.build();
  	}

  }
    1. 在需要生成API文档的Controller和方法内添加注解

      • @Api(tage=“xxx”) xxx为该controller中文描述

      • @ApiOption(“xxx”) xxx 为方法中文描述

      • 示例如下

          package com.ihrm.modules.sys.controller;

  import com.ihrm.common.utils.PageUtils;
  import com.ihrm.common.utils.R;
  import com.ihrm.modules.sys.entity.CoCompanyEntity;
  import com.ihrm.modules.sys.service.CoCompanyService;
  import io.swagger.annotations.Api;
  import io.swagger.annotations.ApiOperation;
  import org.springframework.beans.factory.annotation.Autowired;
  import org.springframework.web.bind.annotation.*;

  import java.util.Arrays;
  import java.util.Map;



  /**
   * 
   *
   * @author gaogzhen
   * @email [email protected]
   * @date 2020-11-16 15:20:30
   */
  @RestController
  @RequestMapping("sys/cocompany")
  @Api(tags = "公司")
  public class CoCompanyController {
  	@Autowired
  	private CoCompanyService coCompanyService;

  	/**
  	 * 列表
  	 */
  	@GetMapping("/list")
  //    @RequiresPermissions("sys:cocompany:list")
  	@ApiOperation("列表")
  	public R list(@RequestParam Map<String, Object> params){
  		PageUtils page = coCompanyService.queryPage(params);

  		return R.ok().put("page", page);
  	}


  	/**
  	 * 信息
  	 */
  	@GetMapping("/info/{id}")
  	// @RequiresPermissions("sys:cocompany:info")
  	@ApiOperation("根据ID查询公司信息")
  	public R info(@PathVariable("id") String id){
  		CoCompanyEntity coCompany = coCompanyService.getById(id);

  		return R.ok().put("coCompany", coCompany);
  	}

  	/**
  	 * 保存
  	 */
  	@PostMapping("/save")
  //    @RequiresPermissions("sys:cocompany:save")
  	@ApiOperation("添加")
  	public R save(@RequestBody CoCompanyEntity coCompany){
  		coCompanyService.save(coCompany);

  		return R.ok();
  	}

  	/**
  	 * 修改
  	 */
  	@PostMapping("/update")
  //    @RequiresPermissions("sys:cocompany:update")
  	@ApiOperation("修改")
  	public R update(@RequestBody CoCompanyEntity coCompany){
  //        ValidatorUtils.validateEntity(coCompany);
  		coCompanyService.updateById(coCompany);

  		return R.ok();
  	}

  	/**
  	 * 删除
  	 */
  	@DeleteMapping("/delete")
  //    @RequiresPermissions("sys:cocompany:delete")
  	@ApiOperation("删除")
  	public R delete(@RequestBody String[] ids){
  		coCompanyService.removeByIds(Arrays.asList(ids));

  		return R.ok();
  	}

  }
    • 运行模块，查看效果，路径-项目路径/swagger-ui.html,如图：[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-czLuDOZm-1605791408234)(./images/swagger-origin.png)]

3、优化API文档显示

3.1、汉化

不难看出，上面显示的API文档基本上英文。第一步，文档汉化,步骤：

  • resources文件夹下创建META-INF/resources/文件夹

  • 把文件swagger-ui.html放入上面的文件夹，详细代码如下：

      <!DOCTYPE html>
  <html>
  <head>
  	<meta charset="UTF-8">
  	<title>Swagger UI</title>
  	<link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-32x32.png" sizes="32x32"/>
  	<link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-16x16.png" sizes="16x16"/>
  	<link href='webjars/springfox-swagger-ui/css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
  	<link href='webjars/springfox-swagger-ui/css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
  	<link href='webjars/springfox-swagger-ui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
  	<link href='webjars/springfox-swagger-ui/css/reset.css' media='print' rel='stylesheet' type='text/css'/>
  	<link href='webjars/springfox-swagger-ui/css/print.css' media='print' rel='stylesheet' type='text/css'/>

  	<script src='webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js' type='text/javascript'></script>
  	<script src='webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script>
  	<script src='webjars/springfox-swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script>
  	<script src='webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script>
  	<script src='webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
  	<script src='webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js' type='text/javascript'></script>
  	<script src='webjars/springfox-swagger-ui/lib/lodash.min.js' type='text/javascript'></script>
  	<script src='webjars/springfox-swagger-ui/lib/backbone-min.js' type='text/javascript'></script>
  	<script src='webjars/springfox-swagger-ui/swagger-ui.min.js' type='text/javascript'></script>
  	<script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js' type='text/javascript'></script>
  	<script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script>
  	<script src='webjars/springfox-swagger-ui/lib/jsoneditor.min.js' type='text/javascript'></script>
  	<script src='webjars/springfox-swagger-ui/lib/marked.js' type='text/javascript'></script>
  	<script src='webjars/springfox-swagger-ui/lib/swagger-oauth.js' type='text/javascript'></script>
  	<script src='webjars/springfox-swagger-ui/springfox.js' type='text/javascript'></script>

  	<!--国际化操作：选择中文版 -->
  	<script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script>
  	<script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>

  </head>

  <body class="swagger-section">
  <div id='header'>
  	<div class="swagger-ui-wrap">
  		<a id="logo" href="http://swagger.io">
  			<img class="logo__img" alt="swagger" height="30" width="30" src="webjars/springfox-swagger-ui/images/logo_small.png" />
  			<span class="logo__title">swagger</span>
  		</a>
  		<form id='api_selector'>
  			<div class='input'>
  				<select id="select_baseUrl" name="select_baseUrl"></select>
  			</div>
  			<div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>
  			<div id='auth_container'></div>
  			<div class='input'><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div>
  		</form>
  	</div>
  </div>

  <div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div>
  <div id="swagger-ui-container" class="swagger-ui-wrap"></div>
  </body>
  </html>

重点就是文中注释下面2行，引入中文包和响应的翻译器。改造之后效果如图：

汉化之后，页面排版感觉有点‘丑’有没有？而且文档不能下载，也就是离线情况下不能查看，下面我们加以优化。[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-e2HGRoAw-1605791408290)(./images/2020-11-19_sinicization-1.png)]

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-lk3WnVsi-1605791408295)(./images/2020-11-19_sinicization-2.png)]

3.2、页面及功能优化

优化主要是前端优化，后端代码部分不变，步骤也很简单，只需引入一个依赖：

  • 引入依赖 swagger-bootstrap-ui

重启模块，原先的swagger-ui.html依然可以访问，新的访问路由-项目路径/doc.html,如图：[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-iMGrhION-1605791408302)(./images/2020-11-19_optimize-1.png)]

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-15aKqMjW-1605791408304)(./images/2020-11-19_optimize-2.png)]

3.3、测试

  1. 填写测试数据

  2. 发送

  3. 查看页面响应，如图：[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-FOtQ0vQD-1605791408339)(./images/2020-11-19_optimize-test.png)]

  4. 查看表中数据，如图：[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-J1aT0aTh-1605791408342)(./images/2020-11-19_optimize-table.png)]

swagger生成文档部分简单介绍到这里，项目需求和基本的架子搭建完毕，下面开始业务逻辑部分。

后记 ：

本项目为参考某马视频开发，相关视频及配套资料可自行度娘或者联系本人。上面为自己编写的开发文档，持续更新。欢迎交流，本人QQ:806797785

    后端JAVA源代码地址:https://gitee.com/gaogzhen/ihrm-parent    // 后端项目
前端项目源代码地址：https://gitee.com/gaogzhen/ihrm-vue    // 前端后台管理系统

猜你喜欢

转载自blog.csdn.net/gaogzhen/article/details/109825907
今日推荐
周排行
Android图片与下拉框
java常用的设计模式之单例模式
zabbix自动化监控之自动注册
杨老师课堂之Excel VBA 程序开发第八讲使用工作表函数
Android 去掉底部虚拟导航栏
Android Studio 3.2 Beta 4 发布，功能改进和修复
Linux-3.5_总线驱动设备
Qt QTableView QStandardItemModel用法
session处理
分享几个实用的方法
每日归档
更多
2025-02-06(0)
2025-02-05(0)
2025-02-04(0)
2025-02-03(0)
2025-02-02(0)
2025-02-01(0)
2025-01-31(0)
2025-01-30(0)
2025-01-29(0)
2025-01-28(0)

代码天地 © 2018 codetd.com

境外服务器   最新电视剧2022