SpringCloud之使用Swagger生成微服务中API文档
随着微服务架构体系的发展和应用, 为了前后端能够更好的集成与对接,同时为了项目的方便交付,每个项目都需要提供相应的API文档。来源:PC端、微信端、H5端、移动端(安卓和IOS端) 传统的API文档编写存在以下几个痛点:对API文档进行更新的时候,需要通知前端开发人员,导致文档更新交流不及时;API接口返回信息不明确大公司中肯定会有专门文档服务器对接口文档进行更新。缺乏...
·
随着微服务架构体系的发展和应用, 为了前后端能够更好的集成与对接,同时为了项目的方便交付,每个项目都需要提供相应的API文档。
来源:PC端、微信端、H5端、移动端(安卓和IOS端)
传统的API文档编写存在以下几个痛点:
对API文档进行更新的时候,需要通知前端开发人员,导致文档更新交流不及时;
API接口返回信息不明确
大公司中肯定会有专门文档服务器对接口文档进行更新。
缺乏在线接口测试,通常需要使用相应的API测试工具,比如postman、SoapUI等
接口文档太多,不便于管理
为了解决传统API接口文档维护的问题,为了方便进行测试后台Restful接口并实现动态的更新,因而引入Swagger接口工具。
Swagger具有以下优点
1.功能丰富:支持多种注解,自动生成接口文档界面,支持在界面测试API接口功能;
2.及时更新:开发过程中花一点写注释的时间,就可以及时的更新API文档,省心省力;
3.整合简单:通过添加pom依赖和简单配置,内嵌于应用中就可同时发布API接口文档界面,不需要部署独立服务。
Swagg er 2.0 集成配置
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.0.5.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.buba</groupId>
<artifactId>demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>demo</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
<spring-cloud.version>Greenwich.RELEASE</spring-cloud.version>
</properties>
<dependencies>
<!-- SpringBoot整合Web组件 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- SpringBoot整合eureka客户端 -->
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>
<!-- swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<!--Finchley.RELEASE 加上这个东西,别使用默认的 或者使用Finchley.M7这个兼容springcloud2.0版本但是我使用不好使-->
<version>Finchley.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
<repositories>
<repository>
<id>spring-milestones</id>
<name>Spring Milestones</name>
<url>https://repo.spring.io/milestone</url>
<!--加上这个false就不从上面这个链接里下载jar包-->
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
</project>
写一个配置类,描述文档一些信息
package com.buba.configuration;
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;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
// 扫包的范围,也就是把哪些包生成api文档
.apis(RequestHandlerSelectors.basePackage("com.buba.controller")).paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
//title文档标题
//description文档描述
//termsOfServiceUrl自定义地址
//version版本号
return new ApiInfoBuilder().title("微服务电商系统").description("微服务swagger")
.termsOfServiceUrl("http://www.buba.com")
// .contact(contact)
.version("1.0").build();
}
}
随便写个controller接口,然后启动项目进行测试,启动后报的错不用管.
package com.buba.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
@Api("aaa")
@Controller
public class SwaggerController {
//描述方法的
@ApiOperation("方法一描述")
//描述参数的 name参数名 value描述信息 required是否必填 dataType参数类型
@ApiImplicitParam(name = "userName",value = "用户名参数",required = true,dataType = "String")
@GetMapping("/swaggerIndex")
public String swaggerIndex(String userName){
System.out.println(userName);
return "index";
}
}
http://localhost:9090/swagger-ui.html访问这个路径就能看到api文档详细信息了
直接在这上面就可以测试
更多推荐
已为社区贡献6条内容
所有评论(0)