【Spring Cloud】Swagger管理微服务API文档

注：文章基于SpringBoot 2.1.1.RELEASE

一、整体架构

• BookService 书城后台服务
• BookWebsite 书城前台服务
• ZuulServer 使用Zuul组件做为网关
• Eureka 使用Eureka组件做为注册中心

二、创建BookService

1. 新建Maven工程
2. pom.xml引入Swagger依赖

<dependency>
    <groupId>com.spring4allgroupId>
    <artifactId>swagger-spring-boot-starterartifactId>
    <version>1.7.0.RELEASEversion>
dependency>

完整pom.xml文件

<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.0modelVersion>

    <groupId>com.springclouddemogroupId>
    <artifactId>BookServiceartifactId>
    <version>1.0-SNAPSHOTversion>

    <parent>
        <groupId>org.springframework.bootgroupId>
        <artifactId>spring-boot-starter-parentartifactId>
        <version>2.1.1.RELEASEversion>
        <relativePath/> 
    parent>

    <properties>
        <java.version>1.8java.version>
        <spring-cloud.version>Greenwich.RC2spring-cloud.version>
    properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-webartifactId>
        dependency>
        <dependency>
            <groupId>org.springframework.cloudgroupId>
            <artifactId>spring-cloud-starter-netflix-eureka-clientartifactId>
        dependency>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-testartifactId>
            <scope>testscope>
        dependency>
        <dependency>
            <groupId>com.spring4allgroupId>
            <artifactId>swagger-spring-boot-starterartifactId>
            <version>1.7.0.RELEASEversion>
        dependency>
    dependencies>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloudgroupId>
                <artifactId>spring-cloud-dependenciesartifactId>
                <version>${spring-cloud.version}version>
                <type>pomtype>
                <scope>importscope>
            dependency>
        dependencies>
    dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.bootgroupId>
                <artifactId>spring-boot-maven-pluginartifactId>
            plugin>
        plugins>
    build>

    <repositories>
        <repository>
            <id>spring-milestonesid>
            <name>Spring Milestonesname>
            <url>https://repo.spring.io/milestoneurl>
        repository>
    repositories>

project>

3. 新建application.yml

#配置服务端口号
server:
  port: 8801
spring:
  application:
    #配置服务名称
    name: BookService
#配置注册中心
eureka:
  client:
    service-url:
      defaultZone: http://localhost:8081/eureka/
swagger:
  #配置Swagger扫包范围
  base-package: com.springclouddemo.bookservice.service

4. 新建启动类BookServiceApp.java

package com.springclouddemo.bookservice;

import com.spring4all.swagger.EnableSwagger2Doc;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.EnableEurekaClient;

@SpringBootApplication
@EnableEurekaClient
@EnableSwagger2Doc
public class BookServiceApp {    
    public static void main(String[] args){
        SpringApplication.run(BookServiceApp.class, args);
    }
}

5. 创建BookService.java

package com.springclouddemo.bookservice.service;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@Api("书城服务接口")
@RestController
public class BookService {
    @ApiOperation("查询书籍信息")
    @GetMapping("/bookInfo")
    @ApiImplicitParam(name = "bookName", value = "书籍名称", required = true, type = "String")
    public String bookInfo(@RequestParam("bookName") String bookName){
        return bookName + "[畅销图书]";
    }
}

6. 查看BookService微服务API接口文档
   浏览器地址栏输入

http://127.0.0.1:8801/swagger-ui.html

三、Zuul网关管理所有微服务API文档

1. 配置文件中添加BookService的转发规则

zuul:
  routes:
    api-bookservice:
      path: /api-bookservice/**
      serviceId: BookService

2. pom.xml引入依赖

<dependency>
    <groupId>com.spring4allgroupId>
    <artifactId>swagger-spring-boot-starterartifactId>
    <version>1.7.0.RELEASEversion>
dependency>

3. 启动类开启Swagger

import com.spring4all.swagger.EnableSwagger2Doc;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.EnableEurekaClient;
import org.springframework.cloud.netflix.zuul.EnableZuulProxy;

@SpringBootApplication
@EnableZuulProxy
@EnableEurekaClient
//启动类开启Swagger2
@EnableSwagger2Doc
public class ZuulserverApplication {
   public static void main(String[] args) {
      SpringApplication.run(ZuulserverApplication.class, args);
   }
}

4. 启动类添加API接口文档来源

import com.spring4all.swagger.EnableSwagger2Doc;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.EnableEurekaClient;
import org.springframework.cloud.netflix.zuul.EnableZuulProxy;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;
import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;

import java.util.ArrayList;
import java.util.List;

@SpringBootApplication
@EnableZuulProxy
@EnableEurekaClient
//启动类开启Swagger2
@EnableSwagger2Doc
public class ZuulserverApplication {
   public static void main(String[] args) {
      SpringApplication.run(ZuulserverApplication.class, args);
   }

   @Primary
   @Component
   class DocumentationConfig implements SwaggerResourcesProvider{
      @Override
      public List<SwaggerResource> get() {
         List<SwaggerResource> swaggerResourceList = new ArrayList<>();
         swaggerResourceList.add(createSwaggerResource("BookService", "/api-bookservice/v2/api-docs ", "1.0"));
         return swaggerResourceList;
      }

      private SwaggerResource createSwaggerResource(String name, String location, String version){
         SwaggerResource swaggerResource = new SwaggerResource();
         swaggerResource.setName(name);
         swaggerResource.setLocation(location);
         swaggerResource.setSwaggerVersion(version);
         return swaggerResource;
      }
   }
}

5. 浏览器输入网关API接口文档地址，查看所有微服务API接口文档
   
   由于篇幅原因，添加BookWebsite微服务API文档不再赘述。如果配置了多个微服务接口文档，则可以在右上方下拉框选择查看。