Java Spring Boot 2.0 API接口实战Swagger和Spring REST Docs帮助文档

内容摘要:基于Java Spring Boot 2.0可以快速开发REST API,但是如何根据API自动生成 Help Docs是非常重要的问题。本次课程详细介绍几种不同的Rest Help Docs的构建方式,Swagger和Rest Docs、OpenAPI核心原理与区别优缺点,并给出Demo代码。
1、API开发、微服务帮助文档解决方法

企业应用接口,目前主要是REST API为主,针对前后端分离架构,或者移动多层架构开发,基于HTTP+JSON方式最为常见。但是API的接口文档一直是个比较棘手的问题,非常重要,几乎每个API开发者都会涉及到接口API文档的编写问题。为接口的调用者提供详细的API文档,成为非常重要的工作内容。

早期Web服务开发者可以使用WSDL,但是REST API无法自动生成文档,目前主流的解决办法,基本是人工编写、或者框架工具生成。
menu_saveimg_savepath20190213141823

2、Swagger 强大的文档工具生态
Java开源的工具生态太强大,Swagger就是其中一个非常经典的工具。为了解决API接口文档的生产问题,国外的技术专家开始编写一些帮助工具插件,其中以Swagger最为有名。开源代码地址:https://github.com/swagger-api/swagger-core
2011年9月开源以后,社区更多的人加入,陆续贡献了验证、测试、UI、规范等新的组件模块。最后有人仿制了其他语言的版本。比如Node、Ruby、C#等版本。

现在Swagger几乎成为API开发必须的工具框架,最早是Tony Tam为公司内部Java项目编写的工具类,生成帮助文档,现在已经是一个完整的API生态,工具,规范,代码生成;包括可视化管理界面。
用于描述,生成,使用和可视化RESTful Web服务;
https://swagger.io/
swagger
Swagger API project 2011 Tony Tam创立 最早Java版;
SmartBear Software公司支持,Apache License 2.0;
早期的Swagger API规范,更名为OpenAPI Spec;成为标准。
Swagger and OAS紧密结合;
Swagger 2 to OpenAPI 3;
现在Swagger 捐赠给linux基金会,;
因为诞生比较早,加上多语言的支持,事实上已经成为行业标准规范;
Swagger 3.0版本改名为OpenAPI 有专门的委员会参与制定规范。
Swagger Tools有提供强大的API工具,包括:设计、开发、测试、监控、治理等领域,十分的强大。

3、Spring Rest Docs 新特性
Spring REST Docs的目标替代SpringFox Swagger,帮助自动化生成RESTful服务的文档。
使用Asciidoctor编写的手写文档;
Spring REST Docs为RESTful服务生成准确且可读的文档。
将手写文档与使用Spring测试生成的文档片段相结合。
不受Swagger等工具生成的文档的限制。
它可以生成准确,简洁和结构良好的API文档。
Spring REST Docs支持测试驱动Test Driven。
Spring REST Docs支持Spring MVC Test框架,Spring WebFlux的WebTestClient或REST Assured 3测试驱动。
Spring Boot 提供了注解@AutoConfigureRestDocs简化文档开发。
但是目前来看,取代Swagger比较难,因为Swagger本身生态系统太强大,而且已经进化成行业标准规范了。Spring Rest Docs 也有人提供扩展的对OpenAPI的支持。
4、Spring Boot 2.0 实战 Swagger2 Demo
首先新建Java Spring Boot 2.0项目,然后加入对应的Swagger依赖,使用2.0版本就可以了。

<!-- Swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-bean-validators</artifactId>
            <version>2.8.0</version>
        </dependency>

API接口使用Swagger注解方式配置,比较方便,提供了。模拟淘宝淘宝订单 API接口OrderController。而且Swagger提供了注解@Api、@ApiModel、@ApiRequest、@ApiResponse等方便进行API开发与设计。

@RestController
@RequestMapping("/api/v1/orders")
@Api(value = " 淘宝订单 API接口, taobao Order REST API", description = "淘宝订单 API接口,api of  orders in TaoBao  System")
public class OrderController {
    @Autowired
    private OrderRepository orderRepository;

    @ApiOperation(value = "查询所有订单,get a list of all orders", response = List.class)
    @ApiResponses(value = { @ApiResponse(code = 200, message = "Successfully retrieved list"),
            @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
            @ApiResponse(code = 404, message = "The resource you were trying to reach is not found") })
    @GetMapping("/getAll")
    public List<Order> getAll() {
        return orderRepository.getAll();
    }

    @ApiOperation(value = "查询单个订单,Get an Order by Id")
    @GetMapping("/getById/{id}")
    public ResponseEntity<Order> getById(
            @ApiParam(value = "Order id from which Order object will retrieve", required = true) @PathVariable(value = "id") Long id) {
        Order order = orderRepository.getById(id);

        return ResponseEntity.ok().body(order);
    }

十分方便,最后配置完成,启动项目,在浏览器中输入地址 http://localhost:8080/swagger-ui.html
可以看到API的帮助文档页面,非常的详细,点击进去可以看到每个API接口详细的参数,请求和返回消息的例子。
swagger_ui

5、Spring Boot 2.0 实战 Rest Docs Demo

 Rest Docs的开发相对比较麻烦,除了依赖,还需要严格的编写Test测试代码,保证测试代码通过,在进行文档生成,帮助文档生成可以使用maven实现。pom配置ASCIIdoctor的生成插件。
<plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.7</version>
                <executions>
                    <execution>
                        <id>generate-docs</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html</backend>
                            <doctype>book</doctype>
                        </configuration>
                    </execution>
                </executions>
                …
</plugin>

项目结构如下,生成文档doc和合并html的目录都可以配置:
SpringBoot_RestDocs_

要编写对应的Test测试代码,保证测试用例成功。Junit4和5版本还存在差别,5使用的是扩展类.4使用的是注解方式。

@Rule
    public JUnitRestDocumentation jUnitRestDocumentation = new JUnitRestDocumentation();

@SpringBootTest
//创建REST Doc for 5.0

@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
public class OrdersControllerJunit5Test {

    private MockMvc mockMvc;

    @BeforeEach
    public void setUp(WebApplicationContext webApplicationContext,
                      RestDocumentationContextProvider restDocumentation) {
        this.mockMvc = MockMvcBuilders
                .webAppContextSetup(webApplicationContext)
                .apply(documentationConfiguration(restDocumentation))
                .build();
    }

    @Test
    public void getPersonByIdShouldReturnOk() throws Exception {
        this.mockMvc.perform(RestDocumentationRequestBuilders.get("/orders/{id}", 1))
                .andExpect(status().isOk())
                .andExpect(content().contentType("application/json;charset=UTF-8"))
                .andDo(document("orders/getById",
                        pathParameters(parameterWithName("id")
                                .description("订单编号")),
                        responseFields(
                                fieldWithPath("id")
                                        .description("订单编号Unique identifier of the order."),
                                fieldWithPath("title")
                                        .description("订单标题title of the order."),
                                fieldWithPath("desc")
                                        .description("订单描述desc of the order."),
                                fieldWithPath("price")
                                        .description("订单价格price of the order.")
                        )
                ));
    }

}

生成的doc分解为碎片模式,可以提供多个不同的碎片文档,分解为不同的请求、应答、消息体、字段等文档。以订单Order接口为例子:
==== CURL 请求
include::{snippets}/orders/get-by-id/curl-request.adoc[]
==== Path 参数
include::{snippets}/orders/get-by-id/path-parameters.adoc[]
==== Request 请求
include::{snippets}/orders/get-by-id/http-request.adoc[]
==== Response 应答字段
include::{snippets}/orders/get-by-id/response-fields.adoc[]
==== Response消息例子
include::{snippets}/orders/get-by-id/http-response.adoc[]
最后可以选择合并生成统一的html。Spring_Rest_Docs_

6、总结

从开发体验、复杂度来看,Swagger更加的方便,配置相对简单。
从广泛程度来看,Swagger3目前已经成为API标准,OpenAPI。

从编程语言,最早支持Java,现在Node、Ruby、C#等y且得到许多语言的支持。

Swagger API工具生态系统支持,可帮助开发人员设计,构建,记录和使用RESTful Web服务。 

支持虽然大多数用户通过Swagger UI工具识别Swagger,
Swagger工具集包括对自动生成文档,代码生成和测试用例支持。
Swagger由SmartBear Software赞助,现在交给Linux基金会以后更加的强大,一直是开源软件的强力支持者,并得到了广泛的采用。
Spring Rest Docs设计目标很好,支持严格的Test Driven测试驱动的开发模式,而且可以编写灵活的Java测试代码,Spring REST Docs支持Spring MVC Test框架,Spring WebFlux的WebTestClient或REST Assured 3测试驱动。
但是开发配置相对繁琐,而且对于测试用例要求必须成功通过,综合对比不如Swagger方式方便,接地气,而且最新的Rest Docs也有扩展支持Open API标准。
7、视频课程
本次课程回顾 https://yq.aliyun.com/articles/684226
视频地址:https://yq.aliyun.com/live/859
PPT地址:https://yq.aliyun.com/live/859

8、阿里巴巴Java群超过2800
直播地址:Java技术进阶群
进群方式:钉钉扫码入群
C926B5D9_9BC2_4452_B14E_7F2F506EDAF9
阿里巴巴MongoDB群
_MongoDB_185

猜你喜欢

转载自yq.aliyun.com/articles/690155
0条评论
添加一条新回复