Spring Boot 之 Swagger

Swagger是一种开源软件,用于以人类可读的格式为REST API构建标准文档。这提供了一个UI,可以轻松理解服务约定,并且消费者可以与服务交互,而无需任何有关底层逻辑的详细知识。

Swagger由SmartBear软件开发,并随附Swagger EditorSwagger CodeGenSwagger UISwagger Inspector等工具。Swagger提供了称为REST API的规范,用于记录REST API。

Swagger可通过以下方式与REST API集成:

  1. 一个自上而下的方法-首先API规范,然后代码生成
  2. 钮式的方法-首先API代码,然后扬鞭整合。当已经内置了现有的REST API并且需要集成Swagger文档时,这是非常熟悉的,并且最有用。

在本文中,我们将学习如何采用自上而下的方法。

阅读更多:Swagger自下而上的方法示例

目录

1。 概述 
2。 技术堆栈 
3。 创建API约定 
4。 生成API代码 
5。 执行API代码 
6。 资源

1.概述

在使用SOAP服务时,我们通常会获得WSDL约定并生成带有完整注解的JAVA代码。像这样,如果我们能够按照OpenAPI规范指定REST约定,则可以使用Swagger CodeGen创建服务器存根和客户端SDK。

我们将看到如何完成此操作以实现预期的REST服务的基本实现。

2.技术栈或开发环境

  • Java 1.7以上
  • Swagger编辑器
  • Swagger CodeGen
  • Spring工具套件
  • Spring Boot
  • Spring休息
  • 马文

3.创建REST API约定

为了创建API约定,为简单起见,我们使用在线Swagger编辑器。您也可以下载并安装相同的文件。

首先创建约定要对OpenAPI规范有所了解。在此演示中,Employee已创建了服务约定,该约定将根据ID查找员工详细信息。

在Swagger编辑器的左窗格中,写下规范。根据规范结果,右窗格将显示Swagger的UI文档。

  • 请遵循内联注解以了解以下规范。
    swagger.yaml
    swagger: '2.0' #version of Swagger
    info: # High Level information of API
      description: Sample Swagger Demo #Give the description of API
      version: 1.0.0 #API version
      title: Swagger Employee Demo # API title
      license: #Swagger license info
        name: Apache 2.0
    host: localhost # Host Name
    basePath: /v1 #Basepath when there are multiple versions of API running
    tags: # Tag information for each API operation。 Multiple tags for multiple API operation
      - name: employee #Tag name
        description: Everything about your Employee #Tag description of API operation
    schemes:
      - http #security schemes
    paths:
      '/findEmployeeDetails/{employeeId}': #Request Mapping path of REST API
        get: #Request method type, GET,POST etc.
          tags: # Refer to created tag above
            - employee
          summary: Find employee by ID #Summary
          description: Returns a single Employee #Description of API operation
          operationId: getEmployeeDetails #Method name
          produces:
            - application/json #Response content type
          parameters:
            - name: employeeId #Input parameter
              in: path #path variable
              description: ID of Employee to return #description of parameter
              required: true #Is mandatory
              type: integer #data type
              format: int64 #data type format, signed 64 bits
          responses: # API response
            '200': #Successful status code
              description: successful operation #Successful status description
              schema:
                $ref: '#/definitions/Employee' #Response object details
            '400': #Unsuccessful response code
              description: Invalid Employee ID supplied #Unsuccessful response description
            '404': #Unsuccessful response code
              description: Employee not found #Unsuccessful response description
    definitions: # Object definition
      Employee: #Employee Object
        type: object
        properties: #Object properties
          id: #Id attribute
            type: integer
            format: int64
          firstName: #Firstname attribute
            type: string
            description: Employee First Name #data type description
          lastName: #Lastname attribute
            type: string #Data type
            description: Employee Last Name #Data type description
        xml:
          name: employee #xml root element when returning xml
  • 将以上规范放在Swagger编辑器的左窗格中,并直观地查看Swagger文档。
  • 从editor将规范另存为yaml文件File>Save as YAML。它将另存为swagger.yaml

4.使用swagger代码生成工具生成API代码

在较早的步骤中,我们已将规范保存为yaml格式。为了进一步生成源代码,该swagger.yaml文件将作为输入源。为了方便起见,使用了Swagger CodeGen工具。

Swagger提供了实用程序jar,可为不同的编程语言和框架生成客户端REST客户端。可以从Swagger Codegen下载最新的稳定版jar 。

要生成客户端,请使用cli来执行以下命令。

创建api代码的命令
java -jar swagger-codegen-cli-2.3.1.jar generate \
  -i swagger.yaml \
  --api-package com.how2codex.example.employee.api \
  --model-package com.how2codex.example.employee.model \
  --group-id com.how2codex.example \
  --artifact-id spring-swagger-codegen-employee \
  --artifact-version 0.0.1-SNAPSHOT \
  -l spring \
  -o spring-swagger-codegen-employee

参数说明:

  • i:Swagger规范源文件
  • api-package:生成的API类的软件包信息
  • model-package:生成的模型类的包装信息
  • group-id:Maven属性
  • artifact-id:Maven属性
  • 工件版本:Maven属性
  • l:实现框架,此处使用Spring,默认情况下提供spring-boot
  • o:输出目录

成功执行上述命令后,spring-swagger-codegen-employee将创建一个Spring Boot Maven项目。

5.发布REST API

  • 打开Spring工具套件并导入为我们在上一步中创建的Maven项目。
  • 导入并成功构建项目后,您会发现将自动创建swagger配置类。
  • 验证API控制器FindEmployeeDetailsApiController.java和关联的接口,您将看到所有Swagger注解均已添加。
    FindEmployeeDetailsApi.java
    @javax.annotation.Generated(value = "io.swagger.codegen.languages.SpringCodegen", date = "2018-03-14T07:52:19.544+05:30")
    @Api(value = "findEmployeeDetails", description = "the findEmployeeDetails API")
    public interface FindEmployeeDetailsApi {
        @ApiOperation(value = "Find employee by ID", nickname = "getEmployeeDetails", notes = "Returns a single Employee", response = Employee.class, tags={ "employee", })
        @ApiResponses(value = {
            @ApiResponse(code = 200, message = "successful operation", response = Employee.class),
            @ApiResponse(code = 400, message = "Invalid Employee ID supplied"),
            @ApiResponse(code = 404, message = "Employee not found") })
        @RequestMapping(value = "/findEmployeeDetails/{employeeId}"
            produces = { "application/json" },
            method = RequestMethod.GET)
        ResponseEntity<Employee> getEmployeeDetails(@ApiParam(value = "ID of Employee to return",required=true) @PathVariable("employeeId") Long employeeId);
    }
    FindEmployeeDetailsApiController.java
    @javax.annotation.Generated(value = "io.swagger.codegen.languages.SpringCodegen", date = "2018-03-14T07:52:19.544+05:30")
    @Controller
    public class FindEmployeeDetailsApiController implements FindEmployeeDetailsApi {
        private static final Logger log = LoggerFactory.getLogger(FindEmployeeDetailsApiController.class);
        private final ObjectMapper objectMapper;
        private final HttpServletRequest request;
        @org.springframework.beans.factory.annotation.Autowired
        public FindEmployeeDetailsApiController(ObjectMapper objectMapper, HttpServletRequest request) {
            this.objectMapper = objectMapper;
            this.request = request;
        }
        public ResponseEntity<Employee> getEmployeeDetails(@ApiParam(value = "ID of Employee to return",required=true) @PathVariable("employeeId") Long employeeId) {
            String accept = request.getHeader("Accept");
            if (accept != null && accept.contains("application/json")) {
                try {
                    return new ResponseEntity<Employee>(objectMapper.readValue("{  \"firstName\" : \"firstName\",  \"lastName\" : \"lastName\",  \"id\" : 0}", Employee.class), HttpStatus.NOT_IMPLEMENTED);
                } catch (IOException e) {
                    log.error("Couldn't serialize response for content type application/json", e);
                    return new ResponseEntity<Employee>(HttpStatus.INTERNAL_SERVER_ERROR);
                }
            }
            return new ResponseEntity<Employee>(HttpStatus.NOT_IMPLEMENTED);
        }
    }
  • 接下来运行该项目,然后打开Swagger UI,可通过访问http://localhost:8080/v1/swagger-ui.html。您可以在Swagger UI中检查所有API详细信息。
    @Controller
    public class HomeController {
        @RequestMapping(value = "/")
        public String index() {
            System.out.println("swagger-ui.html");
            return "redirect:swagger-ui.html";
        }
    }

  • 现在,让我们访问默认的实现服务– findEmployeeDetails/{employeeid}。由于在控制器类中未实现任何业务逻辑,因此您将看到HTTP status code 501 (Not Implemented)。让我们通过Swagger和REST客户端访问REST服务以查看默认响应。
  • Swagger UI请求:
  • Swagger UI响应:
  • REST客户端响应:Postman客户端快照
  • 现在,在实际实施时根据业务需要自定义服务方法。请注意,集成Swagger可以节省很多精力,这对于在任何新API的实现期间准备结构化代码也非常有用。

6.资源

添加了生成的项目,以方便下载部分参考。如果您有任何疑问,请问我。

saigon has written 1445 articles

Leave a Reply