swagger2实战

发布时间:2021-09-21 18:13:50

swagger2实战


一、概论


服务器提供的java服务越来越多,每个服务提供的接口的文档化和自动化可以省略很多不必要的功夫。swagger2提供了这个能力。


二、在线api


swagger2通过在各Controller控制层加注解的方式,获取对每个接口的输入输出格式和http请求格式,整理成接口,前端?swagger-ui解析该接口数据并展示,还提供了对接口的测试功能。


1)? 包依赖


根据不同jdk可适当降低版本。




????io.springfox
????springfox-swagger2
????2.8.0


????io.springfox
????springfox-swagger-ui
????2.8.0

2)? swaggerConfig类配置


注册进spring,并获取springMVC的接口信息。


@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurerAdapter {
??? @Bean
??? public Docket createRestApi(){
??????? return new Docket(DocumentationType.SWAGGER_2)
??????????????? .groupName("v1")
??????????????? .apiInfo(apiInfo())
??????????????? .useDefaultResponseMessages(false)
??????????????? .select()
??????????????? .apis(RequestHandlerSelectors.any())
??????????????? .paths(PathSelectors.ant("/api/v1/**"))
??????????????? .build()
??????????????? .enableUrlTemplating(false);
??? }
??? private ApiInfo apiInfo(){
??????? return new ApiInfoBuilder()
??????????????? .title("使用Swagger2构建RESTful APIs")
??????????????? .description("本人期待更多的技术碰撞!请关注:wangjian090@126.com")
??????????????? .termsOfServiceUrl("wangjian090@126.com")
??????????????? .contact("wangjian")
??????????????? .version("1.0")
??????????????? .build();
??? }
??? @Override
??? public void addResourceHandlers(ResourceHandlerRegistry registry) {
??????? registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
??????? registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
??????? registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
??????? super.addResourceHandlers(registry);
??? }
}

3)? controller配置


各类注解,如@Api在类名上,@ApiOperation在方法上,描述接口的输入输出,点击参考链接 。


@Api(value="areaController",description = "区域")
@RestController
@Scope("prototype")
@RequestMapping("/api/v1/area")
public class AreaController extends BasicController {
?? @ApiOperation(value = "获取区域分页列表",notes = "根据类型和页码")
?? @ApiImplicitParams({
???????? @ApiImplicitParam (name="pageNum",value="页码",paramType = "path",required=true,dataType="Long"),
???????? @ApiImplicitParam (name="pageSize",value="单页数量",paramType = "path",required=true,dataType="Long"),
???????? @ApiImplicitParam (name="type",value="区域类型",paramType = "query",required=true,dataType="Long"),
???????? @ApiImplicitParam (name="name",value="搜索关键字",paramType = "query",required=true,dataType="Long")
?? })
?? @RequestMapping(value="select/{pageNum}/{pageSize}",method=RequestMethod.GET)
?? public Result selectByPage(@PathVariable Long pageNum,@PathVariable Long pageSize,Long type,String name){
????? return new Result(getService().selectListByPage(pageNum,pageSize,type,name));
?? }
}

4)? swagger-ui配置


在springMVC的dispatchServlet 的url匹配是/时,不需要这一步,直接访问地址http://localhost/app/swagger-ui.html#/??即可。


而的url匹配不是/得情况下,需在前端直接存在页面和js。


修改index.html中36行的url为?url = "/app/v2/api-docs.mvc?group=v1";


这时打开http://localhos/app/{swagger2-Path}/swagger2/index.html?即可


{swagger2-Path}为swagger2前端包在所路径


三、离线api


在线api更多的是面向工程师,而不是第三方厂商,这时需要提供离线文档和SDK。swagger2markup是个开源jar包,可以将swagger2提供的接口数据转为常用的html或pdf或word离线文档。有两种方式,一个是java代码实现,一个是maven配置自动实现,这里只展示java实现。


1)? 包依赖


必须jdk1.7以上才支持。




?? io.github.swagger2markup
?? swagger2markup
?? 1.3.1



?? org.asciidoctor
?? asciidoctorj
?? 1.5.6


?? org.asciidoctor
?? asciidoctorj-pdf
?? 1.5.0-alpha.16

repositories里需要增加库地址



???jcenter-realses
???jcenter
???http://jcenter.bintray.com
???
??????false
???


beanutils需要升级到1.9.3



???commons-beanutils
???commons-beanutils
???1.9.3

2)? 转化为ascii.adoc文件


3)? 将ascii.adoc转为html5或pdf


代码如下,根据不同服务,更改SWAGGER_URL和DES_FILE_PATH即可。在DES_FILE_PATH会有.adoc和.html和.pdf三个文件。


?


import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.asciidoctor.*;

import java.io.File;
import java.io.IOException;
import java.net.URL;
import java.nio.file.Paths;
/**
* Created by 31261 on 2018/5/22.
*/
public class SwaggerTest {
??? public static void main(String[] args) throws IOException {
??????? String SWAGGER_URL = "http://127.0.0.1:9080//app/v2/api-docs.mvc?group=v1";//查询的swagger2 json接口
??????? String DES_FILE_PATH = "d://del_file/docs";//下载到目标文件路径
??????? Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
??????????????? .withPathsGroupedBy(GroupBy.TAGS)
??????????????? .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
??????????????? .withOutputLanguage(Language.ZH)
??????????????? .build();//asscii转换配置
??????? Swagger2MarkupConverter
??????????????? .from(new URL(SWAGGER_URL))
??????????????? .withConfig(config)
??????????????? .build().toFile(Paths.get(DES_FILE_PATH+"/asciidoc"));//下载asciidoc.adoc文件
??????? //.adoc文件转化为html5
??????? Asciidoctor asciidoctor = Asciidoctor.Factory.create();
??????? Attributes attributes = new Attributes();
??????? attributes.setCopyCss(true);
??????? attributes.setLinkCss(false);
??????? attributes.setSectNumLevels(3);
??????? attributes.setAnchors(true);
??????? attributes.setSectionNumbers(true);
??????? attributes.setTableOfContents(Placement.LEFT);
??????? attributes.setAttribute("generated",DES_FILE_PATH+"/html");
??????? OptionsBuilder optionsBuilder = OptionsBuilder.options()
??????????????? .backend("html5")
??????????????? .docType("book")
??????????????? .eruby("")
??????????????? .inPlace(true)
??????????????? .safe(SafeMode.UNSAFE)
??????????????? .attributes(attributes);
??????? asciidoctor.convertFile(new ???????? File(DES_FILE_PATH+"/asciidoc.adoc"),optionsBuilder.get());
??????? //.adoc文件转化为pdf
??????? attributes.setAttribute("generated",DES_FILE_PATH+"/pdf");
??????? optionsBuilder.backend("pdf").attributes(attributes);
??????? asciidoctor.convertFile(new File(DES_FILE_PATH+"/asciidoc.adoc"),optionsBuilder.get());
??? }
}

?


?

相关文档

  • 英特尔也在研究无人驾驶汽车 欲搭载自家处理器
  • 勉励自己的经典人生格言
  • 一抹苦绕于心窝一缕情羽化心境
  • 腾讯云申请 ssl 证书+nginx配置https(强制http转https)
  • 通用版样品买卖合同样书
  • 班主任经验交流材料:班主任的“四菜一汤”
  • 电脑换硬盘后出现error:no boot disk has been detected or the disk has failed怎么办
  • 启迪怎样造句
  • 品牌转让合同格式
  • 送给周末客户的祝福语
  • iphone8多少钱
  • 结构化游戏教学计划
  • 字节跳动技术总监自爆:大学javaweb课程
  • 比尔盖茨说他成功的秘诀有哪些
  • 不适应是什么意思
  • 江西宜春学院药学2020年考研招生简章
  • 基本常识选择题
  • 不负蒹葭的诗歌
  • 怎样把一个小学六年级的班级管好
  • 治疗跌打损伤的中成药
  • 苹果手机如何进入恢复模式
  • HTTP请求格式和HTTP响应格式
  • 高中教师节黑板报素材
  • “5G时代”抢占先机 大批“独角兽”企业将崛起
  • 娜丽丝防晒霜好用吗娜丽丝防晒霜使用感受
  • 燃气快速热水器怎么用
  • 关于描写规则的优美段落
  • 描写春天梨花唯美句子
  • 住院医师规培年终总结住院医师规范化培训个人工作总结
  • 描写山水风光的古诗词佳句
  • 猜你喜欢

  • 二年级数学上册竖式计算练*题56
  • 2019高一历史人民版必修一试题:23伟大的抗日战争语文
  • 黄花龙芽的功效与作用
  • 广东商学院2009年广东省内文科各专业录取情况表
  • 2019年超硬材料企业发展战略和经营计划
  • 奥维互动地图怎么添加谷歌地图?
  • (完整word版)北师大版三年级数学上册知识点总结
  • 天津市红桥区2017届高三上学期期末考试(下学期开学考
  • 中秋真情祝福语
  • 在XX区创建国家卫生城市动员大会上的讲话
  • 深圳市龙岗中心城岩溶塌陷光纤传感监测研究
  • byredo护手霜多少钱?byredo护手霜价格
  • [leetcode]152.乘积最大子数组
  • 新版人教版八年级上册英语单词表 按字母排序 全册
  • 描写冬天梅花的作文500字
  • 初中七年级生物下册人教版流动的组织——*课件ppt课件
  • 【最新文档】干部股股长竞职演讲稿-精选word文档 (11页)
  • 驾校办公室主任的工作总结
  • 我眼中的幸福600字作文
  • 比熊犬怎么养
  • 观看公安民警违纪警示教育片心得体会
  • 2014年云南省初中学业水*考试地理试题卷 (1)
  • 2012一级建造师考试辅导:工程经济复习笔记
  • 英文励志文章[1]
  • A1 工程概况表
  • 刚结婚想辞职怎么办理
  • 2014届高考物理第二轮复*方案之电学(新课标版)9-推荐下载
  • 祝福高考的文案合集 高考励志说说
  • 人力资源服务机构设立申请表
  • 《泰康智慧宝贝终身保险(分红型)》条款
  • 北师大版一年级下册数学期末检测试卷
  • 初中地理会考人教版试题及答案
  • 丙肝能不能生孩子?【健康必备常识】
  • 学习计划格式
  • 青春
  • 柠檬怎么吃可以有效减肥
  • 【最新2018】学生会五月工作总结 (5000字)-范文模板 (3页)
  • 公共图书馆网站数字资源服务能力提升策略研究
  • 通达信指标大全_通达信指标大全,筹码起爆最佳的信号抄底位置
  • 5 款 Chrome 插件,第 1 款绝对良心!
  • 贵阳市南明区雅蝶内衣经营部(企业信用报告)- 天眼查
  • 成都三江市政工程有限公司(企业信用报告)- 天眼查
  • 电脑版