【Spring Cloud 基础设施搭建系列】Spring Cloud Demo项目使用Swagger2自动生成RESTful API文档

文章目录

使用Swagger2自动生成RESTful API文档
参考
源代码

使用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","[email protected]"))
                        .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：数据类型