[BE/2주차] Spring Rest Docs 적용기 (3)

Rare·2020년 7월 31일

backend

목록 보기

4/6

Spring REST Docs 사용하는 이유
Spring REST Docs 시작하기
1. build.gradle
2. 전체 흐름
3. 테스트 작성
  - 테스트 세팅 방법
  - 테스트 코드에서 문서 작성 방법
4. adoc(asciidoc) 작성 방법
Spring REST Docs 심화편 (추후 업데이트 예정)

프로젝트를 만들면서 필요한 부분을 정리하고 있습니다.
모호하거나, 잘못된 부분이 있으면 댓글로 남겨주세요! 감사합니다 :)

2.4 adoc(asciidoc) 작성 방법

다음은 index.adoc 작성 형태에 따른 출력 화면이다. asciidoc 문법을 알아보기 보단 쓰이는 형태를 보고 우선 따라해보자. 그 후 입맛에 맞게 고치고 싶다면 더 공부하자.

index.adoc

= Spring REST Docs JUnit 5 Sample
Andy Wilkinson;
:doctype: book
:icons: font
:source-highlighter: highlightjs

Sample application demonstrating how to use Spring REST Docs with JUnit 5.

`SampleJUnit5ApplicationTests` makes a call to a very simple service and produces three
documentation snippets.

One showing how to make a request using cURL:

include::{snippets}/sample/curl-request.adoc[]

One showing the HTTP request:

include::{snippets}/sample/http-request.adoc[]

And one showing the HTTP response:

include::{snippets}/sample/http-response.adoc[]

출력 화면

자주 쓰이는 포맷 예시(열어서 읽어보세요)

출처 : baeldung asciidoc tutorials

= RESTful Notes API Guide
Baeldung;
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 4
:sectlinks:

[[overview]]
= Overview

[[overview-http-verbs]]
== HTTP verbs

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its
use of HTTP verbs.

|===
| Verb | Usage

| `GET`
| Used to retrieve a resource

| `POST`
| Used to create a new resource

| `PATCH`
| Used to update an existing resource, including partial updates

| `DELETE`
| Used to delete an existing resource
|===

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its
use of HTTP status codes.

|===
| Status code | Usage

| `200 OK`
| The request completed successfully

| `201 Created`
| A new resource has been created successfully. The resource's URI is available from the response's
`Location` header

| `204 No Content`
| An update to an existing resource has been applied successfully

| `400 Bad Request`
| The request was malformed. The response body will include an error providing further information

| `404 Not Found`
| The requested resource did not exist
|===

[[overview-hypermedia]]
== Hypermedia

RESTful Notes uses hypermedia and resources include links to other resources in their
responses. Responses are in http://stateless.co/hal_specification.html[Hypertext Application
from resource to resource.
Language (HAL)] format. Links can be found beneath the `_links` key. Users of the API should
not create URIs themselves, instead they should use the above-described links to navigate

[[resources]]
= Resources



[[resources-index]]
== Index

The index provides the entry point into the service.

[[resources-index-access]]
=== Accessing the index

A `GET` request is used to access the index

==== Request structure

include::{snippets}/index-example/http-request.adoc[]

==== Example response

include::{snippets}/index-example/http-response.adoc[]

==== CURL request

include::{snippets}/index-example/curl-request.adoc[]

[[resources-index-links]]
==== Links

include::{snippets}/index-example/links.adoc[]


[[resources-CRUD]]
== CRUD REST Service 

The CRUD provides the entry point into the service.

[[resources-crud-get]]
=== Accessing the crud GET

A `GET` request is used to access the CRUD read.

==== Request structure

include::{snippets}/crud-get-example/http-request.adoc[]

==== Example response

include::{snippets}/crud-get-example/http-response.adoc[]

==== CURL request

include::{snippets}/crud-get-example/curl-request.adoc[]

[[resources-crud-post]]
=== Accessing the crud POST

A `POST` request is used to access the CRUD create.

==== Request structure

include::{snippets}/crud-create-example/http-request.adoc[]

==== Example response

include::{snippets}/crud-create-example/http-response.adoc[]

==== CURL request

include::{snippets}/crud-create-example/curl-request.adoc[]

[[resources-crud-delete]]
=== Accessing the crud DELETE

A `DELETE` request is used to access the CRUD delete.

==== Request structure

include::{snippets}/crud-delete-example/http-request.adoc[]

==== Path Parameters
include::{snippets}/crud-delete-example/path-parameters.adoc[]

==== Example response

include::{snippets}/crud-delete-example/http-response.adoc[]

==== CURL request

include::{snippets}/crud-delete-example/curl-request.adoc[]

[[resources-crud-patch]]
=== Accessing the crud PATCH

A `PATCH` request is used to access the CRUD update.

==== Request structure

include::{snippets}/crud-patch-example/http-request.adoc[]

==== Example response

include::{snippets}/crud-patch-example/http-response.adoc[]

==== CURL request

include::{snippets}/crud-patch-example/curl-request.adoc[]

[[resources-crud-put]]
=== Accessing the crud PUT

A `PUT` request is used to access the CRUD update.

==== Request structure

include::{snippets}/crud-put-example/http-request.adoc[]

==== Example response

include::{snippets}/crud-put-example/http-response.adoc[]

==== CURL request

include::{snippets}/crud-put-example/curl-request.adoc[]

더 자세한 문법은 이 사이트에 가서 알아보자. (한글 번역판)
Asciidoc 기본 사용법