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
今日推荐
火速冲上 GitHub 热榜 —— 开源编程语言、框架哪有这么可爱？
北京人形机器人创新中心发布全球首个纯电驱拟人奔跑的全尺寸人形机器人“天工”
LFOSSA 源来如此公开课 | 掌握云原生未来：CNCF 认证全面攻略与备考秘籍
国产云输入法——仅华为无云端数据上传安全问题
开源日报 | 工业开源项目OGG 1.0；姐姐，你要和我一起配置火狐吗；苹果AI遥遥落后？Fedora 40
开放签电子签章：停止新增，优化体验，前进更进（五一假期前工作）
开源日报 | 中学生开源前端动画引擎；全球首个Llama3 8B中文版开源模型；联想电脑恐出局；Linus讽刺AI炒作
周排行
浏览器对同一域名进行请求的最大并发连接数
React Hook之自定义Hook
【转】MyBatis缓存机制
-Java-泛型
自动化测试常用脚本-发送邮件
LeetCode#859: Buddy Strings
java、Python处理字符串
第二篇の博客
Hadoop伪分布式环境安装
SQL Server进阶（十一）临时表、表变量
每日归档
更多
2024-04-27(56)
2024-04-26(39)
2024-04-25(22)
2024-04-24(36)
2024-04-23(26)
2024-04-22(39)
2024-04-21(0)
2024-04-20(6)
2024-04-19(5)
2024-04-18(0)

代码天地 © 2018 codetd.com

境外服务器   最新电视剧2022