使用Swagger2自动生成RESTful API文档
Swagger2可以帮助我们构建强大的RESTful API文档,具体的我就不多介绍了,可以参考最下面的链接。我直接上代码吧。
- 首先我们需要加入依赖。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
- 加入Swagger2 的配置
package com.cc.cloud.member.swagger2;
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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2 //@EnableSwagger2 注解启用 Swagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.pathMapping("/") //配置映射路径
.select()
.apis(RequestHandlerSelectors.basePackage("com.cc.cloud.member.controller")) //扫描的接口的位置
.paths(PathSelectors.any())
.build().apiInfo(new ApiInfoBuilder()
.title("Swagger2构建RESTful API文档")
.description("Swagger2构建微服务Member RESTful API文档")
.version("1.0.0")
.contact(new Contact("kevin","https://blog.csdn.net/cckevincyh","xxxxxx@gmail.com"))
.license("The Apache License")
.licenseUrl("https://blog.csdn.net/cckevincyh")
.build());
}
}
- 启动服务
结果在启动服务的时候报错了,报错如下。
2019-11-11 20:58:43.929 ERROR [cloud-service-member,,,] 15980 --- [ main] o.s.b.d.LoggingFailureAnalysisReporter :
***************************
APPLICATION FAILED TO START
***************************
Description:
An attempt was made to call the method com.google.common.collect.FluentIterable.concat(Ljava/lang/Iterable;Ljava/lang/Iterable;)Lcom/google/common/collect/FluentIterable; but it does not exist. Its class, com.google.common.collect.FluentIterable, is available from the following locations:
jar:file:/D:/Maven/repository/com/google/guava/guava/18.0/guava-18.0.jar!/com/google/common/collect/FluentIterable.class
It was loaded from the following location:
file:/D:/Maven/repository/com/google/guava/guava/18.0/guava-18.0.jar
Action:
Correct the classpath of your application so that it contains a single, compatible version of com.google.common.collect.FluentIterable
解决方法如下:
加入或者升级guava的依赖
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>20.0</version>
</dependency>
之后我们重启服务。然后访问: http://localhost:8762/swagger-ui.html
即可看到如下的页面。
- 接下来就是创建接口。
package com.cc.cloud.member.controller;
import com.cc.cloud.dto.ResponseResult;
import com.cc.cloud.member.domain.Member;
import com.cc.cloud.member.feign.OrderFeign;
import com.cc.cloud.member.service.MemberService;
import com.google.common.collect.Lists;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;
import java.util.List;
@RefreshScope
@RestController
@RequestMapping("/member")
@Api(tags = "会员相关接口")
public class MemberController {
private OrderFeign orderFeign;
@Value("${cloud.service.member:''}")
private String memberConfig;
@Autowired
private MemberService memberService;
@Autowired
public void setOrderFeign(OrderFeign orderFeign) {
this.orderFeign = orderFeign;
}
@GetMapping("/orders")
@ResponseStatus(HttpStatus.OK)
public List<String> getOrderList() {
return orderFeign.getAllOrderList();
}
@GetMapping("/members")
@ResponseStatus(HttpStatus.OK)
public List<String> getMemberList() {
List<String> memberList = Lists.newArrayList();
memberList.add("member 1");
memberList.add("member 2");
memberList.add("member 3");
return memberList;
}
@GetMapping("/config")
@ResponseStatus(HttpStatus.OK)
public String getMemberConfig() {
return memberConfig;
}
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
@ApiOperation("添加会员的接口")
public ResponseResult addMember(@RequestBody Member member) {
return ResponseResult.success(memberService.addMember(member));
}
@GetMapping
@ResponseStatus(HttpStatus.OK)
@ApiOperation("查找所有的会员接口")
public ResponseResult findAllMembers() {
return ResponseResult.success(memberService.findAllMembers());
}
}
下面简单介绍几个注解:
-
@ApiOperation,整个接口属性配置:
- value:接口说明,展示在接口列表。
- notes:接口详细说明,展示在接口的详情页。
- tags:接口的标签,相同标签的接口会在一个标签页下展示。
- httpMethod:支持的HTTP的方法。
-
@ApiImplicitParams,@ApiImplicitParam的容器,可包含多个@ApiImplicitParam注解
-
@ApiImplicitParam,请求参数属性配置:
- name:参数名称
- value:参数说明
- required:是否必须
- dataType:数据类型
之后我们重启之后访问: http://localhost:8762/swagger-ui.html
就能看到最终的效果了。
参考
SpringBoot集成Swagger(Springfox)自动生成API文档
Spring Boot2 系列教程(十七)SpringBoot 整合 Swagger2
Spring Boot中使用Swagger2构建强大的RESTful API文档
springboot2集成swagger2出现guava包下的The following method did not exist:FluentIterable.class
Spring Boot2.x集成Swagger2 2.9.x解决方案
源代码
https://gitee.com/cckevincyh/spring-cloud-demo/tree/swagger2/