Swagger2 生成 Spring Boot API 文档
2017-05-16 11:17
1086 查看
Swagger2 生成 Spring Boot API 文档
Swagger2 生成 Spring Boot API 文档POM 文件
代码支持
访问地址
Swagger UI
注解
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。本文主要介绍了在 Spring Boot 添加 Swagger 支持, 生成可自动维护的 API 文档。
POM 文件
首先我们需要修改工程的 POM 文件 , 添加 Swagger 的 JAR 包springfox-swagger2
swagger-annotations。
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> <version>1.5.13</version> </dependency>
代码支持
其次我们需要在代码中添加支持,于 Application 同级目录添加 Swagger 配置类.import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.ComponentScan; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; 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; @Configuration @EnableSwagger2 public class Swagger2 { @Bean public Docket config() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .useDefaultResponseMessages(false) .select() .apis(RequestHandlerSelectors.basePackage("com.pxx.xxx.controller")) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Blog系统API文档") .contact(new Contact("作者", "访问地址", "联系方式")) .build(); } }
这里需要注意的是
.apis(RequestHandlerSelectors.basePackage("com.pxx.xxx.controller"))指定了 Swagger 的扫描包名, 假如不指定此项, 在 Spring Boot 项目中, 会生成 base-err-controller 的 api 接口项。
访问地址
Ok. 接下来运行项目, 访问 http://项目启动地址/v2/api-docs , 就可以访问到生成的文档的json结构. (如下图 )具体结构可参阅 Swagger官方示例
Swagger UI
当然, 仅有一份JSON文档,还是无法形成直观的API接口文档,我们还需要一份 UI 工具去直观的显示它。Swagger 官方提供了 Swagger UI 来用于文档界面的生成(官方演示)。其安装也相对来说比较简单。从官方 GitHub https://github.com/swagger-api/swagger-ui 下载整个项目包 、 解压, 然后运行
dist目录中的
index.html即可。 (如下图)
需要注意的是,原始文件中,JSON 文件的来源是固定官方示例,虽然可以收工更改,但是相对来说比较麻烦,所以推荐修改
index.html中
window.onload = function() {
// Build a system
const ui = SwaggerUIBundle({
url:
此处修改为你的JSON文件地址,
dom_id: ‘#swagger-ui’,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: “StandaloneLayout”
})
window.ui = ui
}
注解
OK. 现在所有工作基本就绪,通过添加相应注解就可以快速生成相关接口文档, 这也是个人认为比较好的一点。@Api(description = "文章操作相关接口") @RestController @RequestMapping("/article") public class ArticleController { private final Logger logger = LoggerFactory.getLogger(ArticleController.class); @Autowired private BlogService blogService; @Autowired private JsonMapper jsonMapper; @Autowired private Environment env; @Autowired private PxxHttp pxxHttp; @ApiOperation(value="创建文章", notes="") @RequestMapping(value = {"/create"} , method = RequestMethod.POST) MessageModel create(@ApiParam @RequestParam("params") String params) throws IOException { return result; } @ApiOperation(value="更新文章", notes="") @RequestMapping(value = "/update", method = RequestMethod.POST) public @ResponseBody MessageModel update(@ApiParam @RequestParam("params") String params) throws Exception { return result; } @ApiOperation(value="mns更新文章", notes="") @RequestMapping(value = "/updatearticle", method = RequestMethod.POST) public @ResponseBody MessageModel updateArticle(@ApiParam @RequestParam("params") String params) throws Exception { return result; } }
@Api(description = ""): 对整个 Controller 的定义做一个解释
@ApiOperation(value="", notes=""): 对 Controller 内 function 定义的内容作一解释
@ApiParam: 添加到参数前, Swagger 会自动生成 API 文档中对参数的标示
相关文章推荐
- Swagger2 生成 Spring Boot API 文档
- SwaggerUI自动生成API文档(SwaggerUI+SpringBoot)
- SpringBoot + mybatis + Swagger快速构建REST API并生成优美的API文档
- SpringBoot 自动生成API文档
- SpringBoot开发详解(八) -- 使用Swagger2构建API文档
- Spring boot结合swagger自动生成api文档
- Spring Boot中使用Swagger2生成RESTful API文档(转)
- spring-boot整合swagger生成在线api文档
- SpringCloud SpringBoot mybatis 分布式微服务(二十三)Restdoc生成api文档
- 使用 SpringBoot + Swagger 生成接口 API 文档
- Springboot | SpringBoot 微服务整合Swagger生成API文档
- Spring Boot 使用Swagger2自动生成RESTful API文档
- 使用Spring Boot&Swagger快速构建REST API并生成优美的API文档
- spring boot / cloud (三) 集成springfox-swagger2构建在线API文档
- springboot集成swagger2构建RESTful API文档
- Spring Boot如何让Web API自动生成文档,并解决swagger-annotations的API注解description属性废弃的问题
- SpringBoot:番外篇SpringBoot+Swagger生成可视图的API文档
- SpringBoot&Swagger构建REST API并生成API文档
- SpringBoot实践之---集成Swagger2生成Restful风格的在线API
- Spring Boot 2.0.0.M7 中使用Swagger2构建RESTful API文档