集成SWAGGER2服务

admin管理员组

文章数量:1441360

集成SWAGGER2服务

Swagger 是最流行的用于设计、构建和记录 RESTful API 的工具。它与 Spring Boot 有很好的集成。要将其与 Spring 结合使用，我们需要向 Maven管理文件中 添加以下两个依赖项pom.xml。

代码语言：javascript代码运行次数：0运行复制

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>

单个 Spring Boot 服务的 Swagger 配置非常简单。如果您想为多个分离的微服务创建一个文档，则复杂程度更高。此类文档应在 API 网关上可用。在下图中，您可以看到我们示例解决方案的架构。

首先，我们应该在每个微服务上配置 Swagger。要启用它，我们必须@EnableSwagger2在主类上声明。在应用程序启动期间，Swagger 库将根据源代码自动生成 API 文档。进程由Docket @Bean控制，在主类中声明。我们还使用apiInfo方法设置了一些其他属性，如标题、作者和描述。默认情况下，Swagger 为所有 REST 服务生成文档，包括由 Spring Boot 创建的服务。我们希望将文档仅限于@RestController位于com.microservices.advanced.account.api包中的文档。

1 2 3 4 5 6 7 8 9 10

@Bean public Docket api() throws IOException, XmlPullParserException { MavenXpp3Reader reader = new MavenXpp3Reader(); Model model = reader.read(new FileReader("pom.xml")); return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.microservices.advanced.account.api")) .paths(PathSelectors.any()) .build().apiInfo(new ApiInfo("Account Service Api Documentation", "Documentation automatically generated", model.getParent().getVersion(), null, new Contact("Jack.Yang", "**@163", "**@163"), null, null)); }

这是我们的 API RESTful 控制器。

代码语言：javascript代码运行次数：0运行复制

@RestController
public class AccountController {
 
    @Autowired
    AccountRepository repository;
 
    protected Logger logger = Logger.getLogger(AccountController.class.getName());
 
    @RequestMapping(value = "/accounts/{number}", method = RequestMethod.GET)
    public Account findByNumber(@PathVariable("number") String number) {
        logger.info(String.format("Account.findByNumber(%s)", number));
        return repository.findByNumber(number);
    }
 
    @RequestMapping(value = "/accounts/customer/{customer}", method = RequestMethod.GET)
    public List findByCustomer(@PathVariable("customer") String customerId) {
        logger.info(String.format("Account.findByCustomer(%s)", customerId));
        return repository.findByCustomerId(customerId);
    }
 
    @RequestMapping(value = "/accounts", method = RequestMethod.GET)
    public List findAll() {
        logger.info("Account.findAll()");
        return repository.findAll();
    }
 
    @RequestMapping(value = "/accounts", method = RequestMethod.POST)
    public Account add(@RequestBody Account account) {
        logger.info(String.format("Account.add(%s)", account));
        return repository.save(account);
    }
 
    @RequestMapping(value = "/accounts", method = RequestMethod.PUT)
    public Account update(@RequestBody Account account) {
        logger.info(String.format("Account.update(%s)", account));
        return repository.save(account);
    }
 
}

每个微服务上都存在类似的 Swagger 配置。API 文档位于http://localhost:/swagger-ui.html 下。现在，我们希望为所有微服务启用一个嵌入网关的文档。这是 Spring@Component实现SwaggerResourcesProvider接口，它覆盖 Spring 上下文中存在的默认提供程序配置。

代码语言：javascript代码运行次数：0运行复制

@Component
@Primary
@EnableAutoConfiguration
public class DocumentationController implements SwaggerResourcesProvider {
 
    @Override
    public List get() {
        List resources = new ArrayList<>();
        resources.add(swaggerResource("account-service", "/api/account/v2/api-docs", "2.0"));
        resources.add(swaggerResource("customer-service", "/api/customer/v2/api-docs", "2.0"));
        resources.add(swaggerResource("product-service", "/api/product/v2/api-docs", "2.0"));
        resources.add(swaggerResource("transfer-service", "/api/transfer/v2/api-docs", "2.0"));
        return resources;
    }
 
    private SwaggerResource swaggerResource(String name, String location, String version) {
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation(location);
        swaggerResource.setSwaggerVersion(version);
        return swaggerResource;
    }
 
}

所有微服务 api-docs 都作为 Swagger 资源添加。位置地址通过 Zuul 网关代理。这是网关路由配置。

代码语言：javascript代码运行次数：0运行复制

zuul:
  prefix: /api
  routes:
    account:
      path: /account/**
      serviceId: account-service
    customer:
      path: /customer/**
      serviceId: customer-service
    product:
      path: /product/**
      serviceId: product-service
    transfer:
      path: /transfer/**
      serviceId: transfer-service

现在，API 文档在网关地址http://localhost:8765/swagger-ui.html下可用。您可以在下图中看到它如何查找帐户服务。我们可以在标题面板内的组合框中选择源服务。

通过提供UIConfiguration @Bean. 在下面的代码中，我通过将“list”设置为第二个构造函数参数 - docExpansion 来更改默认操作扩展级别。

代码语言：javascript代码运行次数：0运行复制

@Bean
UiConfiguration uiConfig() {
    return new UiConfiguration("validatorUrl", "list", "alpha", "schema",
            UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS, false, true, 60000L);
}

您可以展开每个操作以查看详细信息。每个操作都可以通过提供所需参数并单击Try it out来测试！按钮。

本文参与 腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。 原始发表：2021-08-16，如有侵权请联系 cloudcommunity@tencent 删除前往查看配置网关springcloud服务

本文标签： 集成SWAGGER2服务