做API-First开发
来源:jhipster |
时间:2018-11-08
|
|

做API-First开发

生成JHipster应用程序时,您可以API first development using OpenAPI-generator在提示其他技术时选择该选项。此选项将配置构建工具以使用OpenAPI生成器从OpenAPI(Swagger)定义文件生成API代码。支持Swagger v2和OpenAPI v3格式。

API-First开发的基本原理

在API第一次开发中,您需要先编写规范,然后从中生成代码,而不是从代码生成文档。这具有以下优点:

  • 您可以为消费者设计API,而不是实施的结果。

  • 您可以使用规范文件在发布之前模拟新的服务器端点,以便您可以更轻松地分离前端和后端开发。

  • 您不需要实时服务器来使用OpenAPI文档。

使用OpenAPI生成器插件

OpenAPI规范文件位于src / main / resources / swagger / api.yml,用于生成可以实现的端点接口。这些接口具有默认方法,它们以501 Not implementedHTTP状态和空体来回答使用诸如swagger-editor之类的工具编写您的规范,将其放入src/main/resources/swagger/api.yml,然后运行:

./mvnw generate-sources

或者为gradle:

./gradlew openApiGenerate

然后执行产生的“代表”的接口${buildDirectory}/generated-sources/openapi/src/main/java/${package}/web/api/@Service类。

为着名的petstore写自己的代码示例

@Servicepublic class PetApiDelegateImpl implements PetApiDelegate {

    @Override
    public ResponseEntity<List<Pet>> findPetsByStatus(List<String> status) {
        return ResponseEntity.ok(
            status.stream()
                .distinct()
                .map(Pet.StatusEnum::fromValue)
                .map(statusEnum -> new Pet().id(RandomUtils.nextLong()).status(statusEnum))
                .collect(Collectors.toList())
        );
    }}

如果将NativeWebRequestbean 提供给委托接口,则将为尚未重写的方法(仍具有501 HTTP状态代码)返回基本示例实体。这在提供实际实现之前模拟端点很有用。

@Servicepublic class PetApiDelegateImpl implements PetApiDelegate {

    private final NativeWebRequest request;

    public PetApiDelegateImpl(NativeWebRequest request) {
        this.request = request;
    }

    @Override
    public Optional<NativeWebRequest> getRequest() {
        return Optional.ofNullable(request);
    }}

然后你可以得到这些例子

$ curl -X GET --header 'Accept: application/json' 'http://localhost:8080/v2/pet/findByStatus?status=pending'{  "photoUrls" : [ "photoUrls", "photoUrls" ],  "name" : "doggie",  "id" : 0,  "category" : {    "name" : "name",    "id" : 6  },  "tags" : [ {    "name" : "name",    "id" : 1  }, {    "name" : "name",    "id" : 1  } ],  "status" : "available"}%$ curl -X GET --header 'Accept: application/xml' 'http://localhost:8080/v2/pet/findByStatus?status=pending'<Pet>  <id>123456789</id>  <name>doggie</name>  <photoUrls>    <photoUrls>aeiou</photoUrls>  </photoUrls>  <tags>  </tags>  <status>aeiou</status></Pet>%


提交
查看更多评论
没有更多评论