儿童主题网站的内容建设,专业的o2o网站建设,wordpress 采集英文插件,揭阳专业网站制作公司Swagger生成JavaDoc在日常的工作中#xff0c;特别是现在前后端分离模式之下#xff0c;接口的提供造成了我们前后端开发人员的沟通成本大量提升#xff0c;因为沟通不到位#xff0c;不及时而造成的[撕币]事件都成了日常工作。特别是很多的开发人员不擅长沟通#xff0c;…Swagger生成JavaDoc在日常的工作中特别是现在前后端分离模式之下接口的提供造成了我们前后端开发人员的沟通成本大量提升因为沟通不到位不及时而造成的[撕币]事件都成了日常工作。特别是很多的开发人员不擅长沟通造成的结果就会让自己特别的痛苦也让合作人员恨的牙根痒痒。为了结束战火蔓延同时为了提升开发人员的满意度Swagger应运而生。什么是SwaggerSwagger for Everyone Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset. Swagger open source and pro tools have helped millions of API developers, teams, and organizations deliver great APIs.简言之就是指使用工具集简化用户、团队和企业的API开发。官方传送门 源码传送门 Swagger-UI传送门 扩展组件swagger-spring-boot-starter传送门 扩展UI组件swagger-bootstrap-ui传送门 集成Swagger系统中我选择使用的是swagger-spring-boot-starter。该项目主要利用Spring Boot的自动化配置特性来实现快速的将swagger2引入spring boot应用来生成API文档简化原生使用swagger2的整合代码。看得出来我在教大家使用的都是在偷懒哦这可不是什么好现象。。。添加依赖 !--整合Swagger2--dependencygroupIdcom.spring4all/groupIdartifactIdswagger-spring-boot-starter/artifactIdversion1.9.0.RELEASE/version/dependency点击版本号进入swagger-spring-boot-starter/1.9.0.RELEASE/swagger-spring-boot-starter-1.9.0.RELEASE.pom可以看到它依赖的版本信息。 propertiesproject.build.sourceEncodingUTF-8/project.build.sourceEncodingversion.java1.8/version.javaversion.swagger2.9.2/version.swaggerversion.spring-boot1.5.10.RELEASE/version.spring-bootversion.lombok1.18.6/version.lombok/properties启用功能在我们的启动类ApiApplication上增加EnableSwagger2Doc注解SpringBootApplication
MapperScan(basePackages com.liferunner.mapper)
ComponentScan(basePackages {com.liferunner, org.n3r.idworker})
EnableSwagger2Doc //启动Swagger
public class ApiApplication {public static void main(String[] args) {new SpringApplicationBuilder().sources(ApiApplication.class).run(args);}Autowiredprivate CORSConfig corsConfig;/*** 注册跨域配置信息** return {link CorsFilter}*/Beanpublic CorsFilter corsFilter() {val corsConfiguration new CorsConfiguration();corsConfiguration.addAllowedOrigin(this.corsConfig.getAllowOrigin());corsConfiguration.addAllowedMethod(this.corsConfig.getAllowedMethod());corsConfiguration.addAllowedHeader(this.corsConfig.getAllowedHeader());corsConfiguration.setAllowCredentials(this.corsConfig.getAllowCredentials());val urlBasedCorsConfigurationSource new UrlBasedCorsConfigurationSource();urlBasedCorsConfigurationSource.registerCorsConfiguration(/**, corsConfiguration);return new CorsFilter(urlBasedCorsConfigurationSource);}
}配置基础信息可以通过properties文件和yml/yaml文件配置。# 配置swagger2
swagger:enabled: true #是否启用swagger默认truetitle: 实战电商api平台description: provide 电商 APIversion: 1.0.0.RClicense: Apache License, Version 2.0license-url: https://www.apache.org/licenses/LICENSE-2.0.htmlterms-of-service-url: http://www.life-runner.comcontact:email: magicianisaacgmail.comname: Isaac-Zhangurl: http://www.life-runner.combase-package: com.liferunnerbase-path: /**阶段效果一运行我们的api项目在浏览器输入http://localhost:8088/swagger-ui.html,可以看到如下可以看到我们在yml文件中配置的信息展示在了页面的顶部点击用户管理:从上图可以看出我们的/users/create接口展出出来并且要传入的参数请求类型等等信息都已经展示在上图中。但是要传递的参数是什么意思都是我们的字段信息我们要如何让它更友好的展示给调用方呢让我们继续完善我们的文档信息完善说明信息在我们创建用户的时候需要传递一个com.liferunner.dto.UserRequestDTO对象这个对象的属性如下RestController
RequestMapping(value /users)
Slf4j
Api(tags 用户管理)
public class UserController {Autowiredprivate IUserService userService;ApiOperation(value 用户详情, notes 查询用户)ApiIgnoreGetMapping(/get/{id})//GetMapping(/{id}) 如果这里设置位这样每次请求swagger都会进到这里是一个bugpublic String getUser(PathVariable Integer id) {return hello, life.;}ApiOperation(value 创建用户, notes 用户注册接口)PostMapping(/create)public JsonResponse createUser(RequestBody UserRequestDTO userRequestDTO) {//...}
}Data
AllArgsConstructor
NoArgsConstructor
Builder
ApiModel(value 创建用户DTO, description 用户注册需要的参数对象)
public class UserRequestDTO {ApiModelProperty(value 用户名, notes username, example isaaczhang, required true)private String username;ApiModelProperty(value 注册密码, notes password, example 12345678, required true)private String password;ApiModelProperty(value 确认密码, notes confimPassword, example 12345678, required true)private String confirmPassword;
}可以看到我们有很多通过Apixxx开头的注解说明这个就是Swagger提供给我们用以说明字段和文档说明的注解。Api 表示对外提供API ApiIgnore 表示不对外展示可用于类和方法 ApiOperation 就是指的某一个API下面的CURD动作 ApiResponses 描述操作可能出现的异常情况 ApiParam 描述传递的单参数信息 ApiModel 用来描述java object的属性说明 ApiModelProperty 描述object 字段说明所有的使用都可以进入到相关的注解的具体class去查看所有的属性信息都比较简单这里就不做具体描述了。想要查看更多的属性说明大家可以进入Swagger属性说明传送门。 配置完之后重启应用刷新UI页面上图中红框圈定的都是我们重新配置的说明信息足够简单明了吧集成更好用的UI界面针对于API说明来说我们上述的信息已经足够优秀了可是做技术我们应该追求的是更加极致的地步上述的UI界面在我们提供大批量用户接口的时候友好型就有那么一丢丢的欠缺了现在给大家再介绍一款更好用的开源Swagger UI有请swagger-bootstrap-ui。我们从上图可以看到这个UI的Star数目已经超过1.1K了这就证明它已经很优秀了我们接下来解开它的庐山真面目吧。集成依赖只需要在我们的expensive-shoppom.xml中加入以下依赖代码 !--一种新的swagger ui--dependencygroupIdcom.github.xiaoymin/groupIdartifactIdswagger-bootstrap-ui/artifactIdversion1.6/version/dependency预览效果添加完依赖后只需要重启我们的应用然后访问http://localhost:8088/doc.html,效果如下点击创建用户上述的效果是不是更符合我们的审美了到此为止我们使用Swagger来动态生成API的效果已经全部演示完了但是如果某一天我们要和一个不能连接查看我们网站的客户进行集成的时候我们怎么办呢还是要手写一份文档给他们吗 那我们不就一样很痛苦吗作为程序员我们是绝对不能允许这种情况发生的那就让我们继续看下去。生成离线文档为了不让我们做痛苦的工作我们既然已经在代码中添加了那么多的说明信息是否有一种方式可以帮助我们来生成一份离线的文档呢答案是肯定的。开源项目swagger2markupA Swagger to AsciiDoc or Markdown converter to simplify the generation of an up-to-date RESTful API documentation by combining documentation that’s been hand-written with auto-generated API documentation.源码传送门documents传送门Swagger2Markup它主要是用来将Swagger自动生成的文档转换成几种流行的格式以便离线使用 格式AsciiDoc、HTML、Markdown、Confluence使用MAVEN插件生成AsciiDoc文档在mscx-shop-apipom.xml中加入以下依赖代码buildplugins!--生成 AsciiDoc 文档(swagger2markup)--plugingroupIdio.github.swagger2markup/groupIdartifactIdswagger2markup-maven-plugin/artifactIdversion1.3.3/versionconfiguration!--这里是要启动我们的项目然后抓取api-docs的返回结果--swaggerInputhttp://localhost:8088/v2/api-docs/swaggerInputoutputDirsrc/docs/asciidoc/generated-doc/outputDirconfigswagger2markup.markupLanguageASCIIDOC/swagger2markup.markupLanguage/config/configuration/plugin/plugins/build http://localhost:8088/v2/api-docs是为了获取我们的api JSON数据如下图src/docs/asciidoc/generated-doc设置我们要生成的目录地址执行命令:expensive-shopmscx-shop-apimvn swagger2markup:convertSwagger2markup要是大家觉得命令太长了也可以点击IDEA Maven mscx-shop-api Plugins swagger2markup swagger2markup:convertSwagger2markup就可以执行啦如下图生成结果如下adoc文件生成好了那么我们使用它来生成html吧使用MAVEN插件生成HTML在mscx-shop-apipom.xml中加入以下依赖代码 !--生成 HTML 文档--plugingroupIdorg.asciidoctor/groupIdartifactIdasciidoctor-maven-plugin/artifactIdversion1.5.6/versionconfigurationsourceDirectorysrc/docs/asciidoc/generated-doc/sourceDirectoryoutputDirectorysrc/docs/asciidoc/html/outputDirectorybackendhtml/backendsourceHighlightercoderay/sourceHighlighterattributestocleft/toc/attributes/configuration/pluginsrc/docs/asciidoc/generated-doc源文件目录指定为我们上一节生成的adoc src/docs/asciidoc/html指定输出目录 执行生成命令expensive-shopmscx-shop-apimvn asciidoctor:process-asciidoc生成结果如下打开overview.html,如下至此我们的文档就已经全部生成了下节预告下一节我们将继续开发我们的用户登录以及首页信息的部分展示在过程中使用到的任何开发组件我都会通过专门的一节来进行介绍的兄弟们末慌gogogo奔跑的人生 | 博客园 | segmentfault | spring4all | csdn | 掘金 | OSChina | 简书 | 头条 | 知乎 | 51CTO
