使用Spring Boot和Swagger进行API优先开发 - reflectoring.io

20-03-24 banq

遵循API优先方法,我们在开始编码之前先指定一个API。通过API描述语言,团队可以进行协作而无需执行任何操作。

使用OpenAPI,我们可以创建一个API规范,我们可以在团队之间共享以交流合同。OpenAPI Maven插件使我们可以根据这样的规范为Spring Boot生成样板代码,因此我们只需要自己实现业务逻辑即可。

这些描述语言指定了端点,安全性模式,对象模式等。而且,大多数时候我们也可以生成这样的规范代码。通常,API规范也成为该API的文档。

您可以在GitHub上浏览示例代码。

API优先的好处

要开始进行组件或系统之间的集成,团队需要签订合同。在我们的案例中,合同是API规范。API-first帮助团队之间相互通信,而无需实现任何事情。它还使团队可以并行工作。

API优先方法的亮点在于构建更好的API。仅关注需要提供的功能。简约的API意味着需要维护的代码更少。

使用Swagger编辑器创建API规范

让我们在YAML文档中创建自己的OpenAPI规范。为了更容易理解,我们将讨论分为正在创建的YAML文档的各个部分。如果您想了解有关OpenAPI规范的更多详细信息,可以访问Github存储库

我们从文档顶部的一些有关API的常规信息开始:

openapi: 3.0.2
info:
  title: Reflectoring
  description: "Tutorials on Spring Boot and Java."
  termsOfService: http://swagger.io/terms/
  contact:
    email: petros.stergioulas94@gmail.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.0.1-SNAPSHOT
externalDocs:
  description: Find out more about Reflectoring
  url: https://reflectoring.io/about/
servers:
- url: https://reflectoring.swagger.io/v2

openapi字段允许我们定义文档遵循的OpenAPI规范的版本。

在这一info部分中,我们添加了有关API的一些信息。这些字段应该是不言自明的。

最后,在本servers节中,我们提供了实现API的服务器列表。

然后是关于我们的API的一些其他元数据:

tags:
- name: user
  description: Operations about user
  externalDocs:
    description: Find out more about our store
    url: http://swagger.io

tags部分提供了其他元数据的字段,我们可以使用这些字段使我们的API更具可读性并易于遵循。我们可以添加多个标签,但是每个标签都应该是唯一的。

接下来,我们将描述一些路径。路径保存有关单个端点及其操作的信息:

paths:
  /user/{username}:
    get:
      tags:
      - user
      summary: Get user by user name
      operationId: getUserByName
      parameters:
      - name: username
        in: path
        description: 'The name that needs to be fetched. '
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        404:
          description: User not found
          content: {}

$ref字段允许我们引用自定义模式中的对象。在这种情况下,我们指的是User架构对象(请参阅下一节有关Components)。summary是该操作的简短说明。使用operationId,我们可以为操作定义唯一的标识符。我们可以将其视为我们的方法名称。最后,responses对象允许我们定义操作的结果。我们必须为任何操作调用至少定义一个成功的响应代码。

组件

本components节中全部介绍了API的对象。除非我们从组件对象外部的属性中明确引用了它们,否则在组件对象中定义的对象将不会影响API,如上所述:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
        firstName:
          type: string
        ... more attributes
        userStatus:
          type: integer
          description: User Status
          format: int32
  securitySchemes:
    reflectoring_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: http://reflectoring.swagger.io/oauth/dialog
          scopes:
            write:users: modify users
            read:users: read users
    api_key:
      type: apiKey
      name: api_key
      in: header

schemas部分允许我们定义要在API中使用的对象。在本securitySchemes节中,我们可以定义操作可以使用的安全性方案。有两种使用安全方案的可能方法。

首先,我们可以使用security字段将安全方案添加到特定操作:

paths:
  /user/{username}:
    get:
      tags:
      - user
      summary: Get user by user name
      security: 
        - api_key: []

在上面的示例中,我们明确指定使用api_key我们上面定义的方案保护路径/ user / {username} 。

但是,如果我们要在整个项目中应用安全性,则只需将其指定为顶级字段即可:

paths:
  /user/{username}:
    get:
      tags:
      - user
      summary: Get user by user name
security: 
  - api_key: []

现在,我们的所有路径都应通过该api_key方案来保证。

从API规范生成代码

定义了API之后,我们现在将根据上面YAML文档创建代码。

我们将研究两种不同的生成代码的方法:

1.从Swagger编辑器生成代码

尽管这是我不会采用的方法,但让我们讨论一下并讨论为什么我认为这是一个坏主意。

让我们转到Swagger Editor,然后将我们的YAML文件粘贴到其中。然后,我们从菜单中选择“ 生成服务器”,然后选择我们要生成哪种服务器(我使用“ Spring”)。

那么,为什么这是个坏主意呢?

首先,为我生成的代码是使用Java 7和Spring Boot 1.5.22,它们都已经过时了。

其次,如果我们对规范进行更改(并且更改始终在发生),我们将不得不复制并粘贴手动更改的文件。

2.使用OpenAPI Maven插件生成代码

更好的替代方法是使用OpenAPI Maven插件从Maven构建中生成代码。

让我们看一下文件夹结构。我选择使用一个多模块Maven项目,其中有两个项目:

  • app,它是根据我们的规范实现API的应用程序。
  • specification,其唯一的工作就是为我们的应用提供API规范。

文件夹结构如下所示:

spring-boot-openapi
├── app
│   └── pom.xml
│   └── src
│       └── main
│           └── java
│               └── io.reflectoring
│                   └── OpenAPIConsumerApp.java
├── specification
│   └── pom.xml
│   └── src
│       └── resources
│           └── openapi.yml
└── pom.xml

为了简单起见,我们省略了测试文件夹。

我们app是一个简单的Spring启动的项目,我们可以自动生成上start.spring.io,让我们着眼于pom.xml从specification模块,在那里我们配置的OpenAPI Maven插件:

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>4.2.3</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>
                  ${project.basedir}/src/main/resources/openapi.yml
                </inputSpec>
                <generatorName>spring</generatorName>
                <apiPackage>io.reflectoring.api</apiPackage>
                <modelPackage>io.reflectoring.model</modelPackage>
                <supportingFilesToGenerate>
                  ApiUtil.java
                </supportingFilesToGenerate>
                <configOptions>
                    <delegatePattern>true</delegatePattern>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

您可以在GitHub上查看完整pom.xml文件。

在本教程中,我们使用spring生成器。

简单地运行命令./mvnw install将生成实现我们的OpenAPI规范的代码!

查看文件夹target/generated-sources/openapi/src/main/java/io/reflectoring/model,我们找到了User在YAML中定义的模型的代码:

@javax.annotation.Generated(...)
public class User   {
  @JsonProperty("id")
  private Long id;

  @JsonProperty("username")
  private String username;

  @JsonProperty("firstName")
  private String firstName;
  
  // ... more properties

  @JsonProperty("userStatus")
  private Integer userStatus;

  // ... getters and setters

}

生成器不仅生成模型,还生成端点。让我们快速看一下我们生成的内容:

public interface UserApiDelegate {

    default Optional<NativeWebRequest> getRequest() {
        return Optional.empty();
    }

    /**
     * POST /user : Create user
     * Create user functionality
     *
     * @param body Created user object (required)
     * @return successful operation (status code 200)
     * @see UserApi#createUser
     */
    default ResponseEntity<Void> createUser(User body) {
        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);

    }
  // ... omit deleteUser, getUserByName and updateUser
}

当然,生成器无法为我们生成我们的业务逻辑,但是它确实会UserApiDelegate为我们实现上述接口。

它还创建一个UserApi接口,将调用委托给UserApiDelegate:

@Validated
@Api(value = "user", description = "the user API")
public interface UserApi {

    default UserApiDelegate getDelegate() {
        return new UserApiDelegate() {};
    }

    /**
     * POST /user : Create user
     * Create user functionality
     *
     * @param body Created user object (required)
     * @return successful operation (status code 200)
     */
    @ApiOperation(value = "Create user", 
      nickname = "createUser", 
      notes = "Create user functionality", 
      tags={ "user", })
    @ApiResponses(value = { 
        @ApiResponse(code = 200, message = "successful operation") })
    @RequestMapping(value = "/user",
        method = RequestMethod.POST)
    default ResponseEntity<Void> createUser(
      @ApiParam(value = "Created user object" ,required=true )  
      @Valid 
      @RequestBody User body) {
        return getDelegate().createUser(body);
    }
    
    // ... other methods omitted
}

生成器还为我们创建了一个Spring控制器,用于实现UserApi接口:

@javax.annotation.Generated(...)
@Controller
@RequestMapping("${openapi.reflectoring.base-path:/v2}")
public class UserApiController implements UserApi {

    private final UserApiDelegate delegate;

    public UserApiController(
      @Autowired(required = false) UserApiDelegate delegate) {
        this.delegate = Optional.ofNullable(delegate)
            .orElse(new UserApiDelegate() {});
    }

    @Override
    public UserApiDelegate getDelegate() {
        return delegate;
    }
}

如果Spring UserApiDelegate在应用程序上下文中找到我们的实现,它将注入到控制器的构造函数中。否则,将使用默认实现。

让我们启动应用程序并点击GET端点/v2/user/{username}。

curl -I http://localhost:8080/v2/user/Petros
HTTP/1.1 501
Content-Length: 0

但是为什么我们会收到501响应(未实现)?

因为我们没有实现UserApiDelegate接口,所以UserApiController使用了默认接口,该接口 返回HttpStatus.NOT_IMPLEMENTED。

现在让我们实现UserApiDelegate:

@Service
public class UserApiDelegateImpl implements UserApiDelegate {

    @Override
    public ResponseEntity<User> getUserByName(String username) {
        User user = new User();
        user.setId(123L);
        user.setFirstName("Petros");
        
        // ... omit other initialization

        return ResponseEntity.ok(user);
    }
}

在类中添加@Service或@Component批注很重要,以便Spring可以将其拾取并注入到中UserApiController。

如果现在curl http://localhost:8080/v2/user/Petros再次运行,将收到有效的JSON响应:

{
  "id": 123,
  "firstName": "Petros",
  // ... omit other properties
}

我认为,使用Maven插件而不是Swagger Editor生成OpenAPI规范是更好的选择。那是因为我们对我们的选择有更多的控制权。该插件提供了一些配置和使用Git作为版本控制工具,我们可以放心地跟踪在任的任何变化pom.xml和openapi.yml。

可以在GitHub上浏览示例代码。

              

猜你喜欢