Apache 软件基金会发表 Apache Juneau 孵化成功,进级为甲级项目。

JAX-RS

JAX-RS: Java API for RESTful Web
Services
是二个Java编程语言的应用程序接口,扶助依据 表象化状态调换(REST卡塔尔(قطر‎结构风格创立Web服务。JAX-EnclaveS使用了 ++Java SE 5++ 引进的Java
标记来简化Web服务客户端和服务端的支出和构造。

本文由码农网 –
Pansanday原创翻译,转发请看清文末的转发须求,接待加入大家的付费投稿安顿!

Apache Juneau 是二个集中框架, 允许开辟者编组 POJO(普通 Java
对象)和开荒 REST(表征状态转移)微服务和 API ,近些日子被 IBM、The Open
Group 和 Salesforce 等公司应用。具体功用富含:

正式内容

JAX-奇骏S提供了有的标记将一个财富类,二个POJOJava类,封装为Web财富。标明包含:

  • 澳门新葡萄京所有网站,@Path,标记财富类或措施的相对路线
  • @GET,@PUT,@POST,@DELETE,注脚情势是用的HTTP央浼的项目
  • @Produces,标记重临的MIME媒体类型
  • @Consumes,标记可肩负央浼的MIME媒体类型
  • @PathParam,@QueryParam,@HeaderParam,@CookieParam,@MatrixParam,@FormParam,分别标记格局的参数来自于HTTP央浼的不如地方,比如@PathParam来自于U奥迪Q3L的门径,@QueryParam来自于U奥迪Q3L的询问参数,@HeaderParam来自于HTTP诉求的头音信,@CookieParam来自于HTTP央求的库克ie。

在上一篇小说中,作者谈起了使用Spring Boot创建RESTFul劳务的阅世。当创制八个REST
API的时候,合适的文书档案是很要紧的一有些。

  • 运用通用框架将 POJO 编组到种种内容类型的工具包。

  • REST 服务器 API,通过运用 POJO 创设基于 Swagger 的 Self-documenting
    REST 接口。

  • 经过应用 POJO 与 REST 接口进行相互影响的 REST 顾客端 API 。

  • 据他们说 REST 营造的长间隔代理 API 。

  • 三个犬牙相制的 INI 配置文件 API 。

  • REST 微服务
    API,结合了上述全体机能,用于创立以微秒为单位运维的轻量级独立 REST
    接口。

JAX-RS的实现

  • Apache CXF,开源的Web服务框架。
  • Jersey, 由Sun提供的JAX-LANDS的参阅完毕。
  • RESTEasy,JBoss的实现。
  • Restlet,由杰罗姆 Louvel和DavePawson开荒,是最先的REST框架,先于JAX-WranglerS现身。
  • Apache
    Wink,叁个Apache软件基金会照蛋器中的项目,其服务模块完毕JAX-奥迪Q5S标准

Swagger是什么

Swagger(Swagger 2)是描述和记录REST
API的叁个规范。它钦点了REST
Web服务的格式,包罗U悍马H2L,能源,方法等。Swagger将从应用程序代码生成文档,并拍卖渲染部分。

在此篇作品中,笔者会将Swagger 2文书档案集成到基于Spring Boot的REST
Web服务中。小编将利用Springfox落实来生成swagger文书档案。纵然您想清楚是如何运转/营造Spring
Boot项指标,请参谋我上一篇文章。

Springfox提供了多个依附关系来生成API文档和Swagger
UI。假若你不希望将Swagger UI集成到您的API中,则无需加多Swagger
UI信赖关系。

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.7.0</version>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.7.0</version>

</dependency>

@
EnableSwagger2批注启用了Springfox
Swagger在类中的帮助。为了记录那么些服务,Springfox使用了贰个Docket类。Docket有利于配置要记录的劳务,并因此名称等举办分组。后台是Springfox通过应用基于Spring配置的API语义,在运维时检查应用程序。换句话说,你必须创建三个施用Spring的@Configuration注脚的Spring
Java Configuration类。

在本人的例证中,小编会生成三个依照本身增多的RestController类的swagger文书档案。

import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class ApplicationConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chandana.helloworld.controllers"))
                .paths(PathSelectors.any())
                .build();
    }
}

由于自家加多了多个调控器,由此将各自对各种调控器相关的API实行分组(标识)。

澳门新葡萄京所有网站 1

开箱即用,Springfox提供了5种断言,它们分别是any,none,withClassAnnotation,withMethodAnnotation和basePackage【译者注:参见springfox.documentation.builders. RequestHandlerSelectors类】

Apache Juneau 手艺副首席履行官 詹姆士 Bognar 代表:“大家平昔大力使 Apache
Juneau 的代码尽也许地大约易用。 我们从事于丰硕和完善Juneau 的成效,并成功创设贰个有利于推进项近来程的多元化社区。我们十一分骄矜Juneau 结业为 Apache 一级项目。“

说明

Java EE 6 引进了对 JS奥迪Q3-311 的扶植。JS途乐-311(JAX-WranglerS:Java API for RESTful
Web Services)目的在于定义一个归总的正经八百,使得 Java
技师能够使用一套固定的接口来开拓 REST
应用,幸免了注重于第三方框架。同有的时候间,JAX-哈弗S 使用 POJO
编制程序模型和依照标明的布局,并集成了 JAXB,从而能够有效收缩 REST
应用的开荒周期。

JAX-RS 定义的 API 位于 javax.ws.rs 包中。

JAX-昂科雷S 的实际完成由第三方提供,举例 Sun 的参谋实现 Jersey、Apache 的 CXF
以至 JBoss 的 RESTEasy。

ApiInfo

Swagger提供了一部分默许值,比如“API文书档案”,“通过联系人电子邮件创制”,“Apache
2.0”。当然你能够透过增加apiInfo(ApiInfo
apiInfo)方法来改造那一个私下认可值。ApiInfo类包蕴关于API的自定义消息。

@Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chandana.helloworld.controllers"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo getApiInfo() {
        Contact contact = new Contact("Chandana Napagoda", "http://blog.napagoda.com", "cnapagoda@gmail.com");
        return new ApiInfoBuilder()
                .title("Example Api Title")
                .description("Example Api Definition")
                .version("1.0.0")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .contact(contact)
                .build();
    }

若是增多了ApiInfo,生成的文书档案看起来就好像那样:

澳门新葡萄京所有网站 2

澳门新葡萄京所有网站 3

Controller和POJO层文档

@Api评释用于注明每一种调整器类(有一些像类注释)。

@ApiOperation申明用于描述财富和方式。

@ApiResponse表明用于注脚操作重临的任何响应值。比如:200
ok或202 accepted等

@ApiModelProperty注明用来描述POJO(Bean)类的习性(属性描述)。

丰硕上述注释后,最终生成的swagger文书档案如下所示:

澳门新葡萄京所有网站 4

Spring RestController类:

package com.chandana.helloworld.controllers;

import com.chandana.helloworld.bean.Greeting;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
@Api(value = "user", description = "Rest API for user operations", tags = "User API")
public class HelloWorldController {

    @RequestMapping(value = "/hello/{name}", method = RequestMethod.GET, produces = "application/json")
    @ApiOperation(value = "Display greeting message to non-admin user", response = Greeting.class)
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "OK"),
            @ApiResponse(code = 404, message = "The resource not found")
    }
    )
    public Greeting message(@PathVariable String name) {
        Greeting msg = new Greeting(name, "Hello " + name);
        return msg;
    }
}

Greeting模型类:

package com.chandana.helloworld.bean;

import io.swagger.annotations.ApiModelProperty;

public class Greeting {

    @ApiModelProperty(notes = "Provided user name", required =true)
    private String player;

    @ApiModelProperty(notes = "The system generated greeting message" , readOnly =true)
    private String message;

    public Greeting(String player, String message) {
        this.player = player;
        this.message = message;
    }

    public String getPlayer() {
        return player;
    }

    public void setPlayer(String player) {
        this.player = player;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

AppConfig类:

package com.chandana.helloworld.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class ApplicationConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chandana.helloworld.controllers"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo getApiInfo() {
        Contact contact = new Contact("Chandana Napagoda", "http://blog.napagoda.com", "cnapagoda@gmail.com");
        return new ApiInfoBuilder()
                .title("Example Api Title")
                .description("Example Api Definition")
                .version("1.0.0")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .contact(contact)
                .build();
    }
}

您也足以从我的GitHub repo 下载  Swagger Spring Boot
Project 源代码。

译者注:

  1. 即使您对Spring Boot不是很熟识,建议先fork下源码,因为有一些信任文中未有关联。
  2. 起步Spring Boot后,在浏览器中输入:127.0.0.1:8080/swagger-ui.html就能够查看生成的文档音讯。

在转换的文书档案页面中,能够输入参数,点击“Try it
out!”就能够进展接口测验,有一点形似于Postman的机能。

(文/开源中中原人民共和国卡塔尔