'gradle'에 해당하는 글 19건

CodeBuild / CodePipeline

Server/AWS 2021. 12. 18. 00:09

aws-eks-ci-cd

 

EKS 에서의 CI / CD 를 고민중이다. AWS 리소스만을 이용하는 방법, 범용적인 CI/CD 를 사용하는 방법... ArgoCD, TerraForm, Jenkins 등 뭐가 많지만 되도록 AWS 리소스를 사용해 보기로 했다. 예전에 ECS 배포할 때는 gradle 에서 Docker 이미지 생성 / ECR 업로드 / 배포까지... 전부 해결했었다. 로컬에서 태스크만 실행하면 되니 build.gradle 만 기다랗게 작성하는 것 빼고는 별 문제가 없었다. 그 때의 애로사항은 배포하려는 개발자의 PC 에 Docker 가 실행되고 있어야 한다는 점. ECR 인증키가 git 에 포함된다는 점. 배포시 오류가 발생한다면 즉시 파악이 어려운 점... 트집을 잡자면 그 정도. 하지만 대부분의 개발자가 docker 를 사용하고, git 도 프라이빗, 배포시 오류는 알림으로 처리했었고... 라며 흡족하게는 썼었지만, 이번엔 왠지 도구를 이용해야만 할 것 같은 느낌적인 느낌. 시간 있으면 이것저것 다 써보는게 좋은거지. 싶어서 CodeCommit, CodeBuild, CodePipeline 을 사용해 보았다.

 

 

사용할 AWS CI/CD Resource

 

  • CodeCommit
    - git 저장소 / 소스 위치
  • CodeBuild
    - 소스코드를 가져와 Test/Build 실행.
    - 자체 컴퓨팅으로 docker 이미지 생성, ECR 이미지 업로드, EKS 배포에 관한 빌드사양 파일 작성(buildspec.yml)
  • CodePipeline
    - git 저장소에 소스코드 변경이 감지되었을 때, source 아티팩트 S3 업로드 후 CodeBuild 실행

 

 

CodeBuild 생성

 

AWS 관리콘솔에서 빌드 프로젝트 만들기

  • 관리형 이미지 컴퓨팅 선택
  • 역할 이름 : 여러 빌드 프로젝트를 관리한다면 하나로 재사용
  • 권한이 있음(privileged) : 도커 이미지를 빌드하거나 빌드의 권한을 승격시 필요
  • VPC / 컴퓨터 유형 선택 : 빌드 성능 결정
  • 환경 변수 : buildspec 에 노출하고 싶지 않은 키/값 지정
  • Buildspec 이름 : 실제 buildspec 파일의 경로 지정
  • 캐시 유형 : 로컬 (DockerLayerCache, SourceCache, CustomCache)
  • 나머지 기본값

 

 

buildspec.yml 파일 작성

 

빌드 프로젝트 생성시 설정한 경로에서 buildspec.yml 를 작성한다. 기본적으로 4개의 페이즈가 있다.

  • install : 빌드 환경 구성
  • pre_build : 빌드에 필요한 ECR 로그인이나 패키지 종속성 설치 등
  • build : 빌드 실행
  • post_build : 빌드 결과물 처리, ECR 이미지 푸시, 빌드 알림 등

 

페이즈 마다의 규칙이 있지는 않지만, 추후 구간별 처리 속도를 알 수 있으므로 구분하여 사용자 정의.

 

$ vi buildspec.yml

version: 0.2

phases:
  install:
    runtime-versions:
      java: corretto11
    commands:
      - curl -o kubectl https://amazon-eks.s3-us-west-2.amazonaws.com/1.21.2/2021-07-05/bin/linux/amd64/kubectl
      - chmod +x ./kubectl
      - mv ./kubectl /usr/local/bin/kubectl
      - aws --version
      - aws eks update-kubeconfig --region ap-northeast-2 --name example-cluster
      - kubectl get po -n exapi
  pre_build:
    commands:
      - echo pre_build Logging in to Amazon ECR...
      - $(aws ecr get-login --region $AWS_DEFAULT_REGION --no-include-email)
      - REPOSITORY_URI=${REPO_ECR}
      - COMMIT_HASH=$(echo $CODEBUILD_RESOLVED_SOURCE_VERSION | cut -c 1-7)
      - IMAGE_TAG=${COMMIT_HASH:=latest}
  build:
    commands:
      - echo Build started on `date`
      - gradle --version
      - chmod +x gradlew
      - ./gradlew :ApiFacility:build
      - docker build -t $REPOSITORY_URI:latest ./Api
      - docker tag $REPOSITORY_URI:latest $REPOSITORY_URI:$IMAGE_TAG
  post_build:
    commands:
      - echo Build completed on `date`
      - echo Pushing the Docker images...
      - docker push -a $REPOSITORY_URI
      #- kubectl apply -f ./AWS/example-deployment.yaml
      - kubectl rollout restart -f ./AWS/example-deployment.yaml

 

위에 정의한 사양은,

  • install : 자바환경, kubectl 설치, kubeconfig 구성
  • pre_build : ECR 로그인, ECR 경로, 이미지 태그명 정의
  • build : gradle 빌드, docker 이미지 생성
  • post_build : ECR 이미지 푸시, eks deployment 롤링 업데이트

 

또한, 위 사양처럼 REPO_ECR 등의 프라이빗 정보들은 빌드 프로젝트 구성시 환경변수로 지정한 변수명으로 사용할 수 도 있다. echo 나 이미지 태깅 관리 때문에 조금 길어지긴 했는데 필요에 맞게 사용자 정의...

 

 

CodePipeline 생성

 

AWS 관리콘솔에서 파이프라인 생성

  • 역할 이름 : 여러 파이프라인을 관리한다면 하나로 재사용
  • 아티팩트가 업로드 될 버킷 위치 수동 지정시
  • 소스 스테이지 : CloudWatch 로 변경 감지, 출력 아티팩트 형식은 기본값을 사용하여 zip 형식의 데이터를 사용해도 무방하지만 간단히 메타데이터만 전달하는 전체 복제 선택.(gitpull 권한 추가 필요)
  • 빌드 스테이지 추가 후 배포 스테이지 건너뛰기

 

 

배포 테스트

 

CodePipeline 이 생성되면 즉시 실행이 되는데, 아니면 수동으로 빌드하던지, git 소스를 푸시하던지... 해서 배포 롤링 업데이트 확인까지. 이제부터는 에러의 향연이다. CodeBuild 의 플로우를 보면 거의 모든 단계에 해당 리소스에 대한 권한이 필요하므로 생성한/된 codebuildrole 에 각 권한을 추가해 주면 된다. 

 

[에러 모음 링크]

 

마치 일부러 에러를 찾아내려는 듯한 치밀한 실수들이 많았다; awscli 버전이 1.2 라 추후 문제가 있을수도 있지 않을까 하는 걱정도 되고... CodeCommit, CodeBuild, CodePipeline, ECR, EKS 등 AWS 리소스 만으로 CI/CD 를 구성해 본 느낌은... 그냥 그렇다.ㅋ 뭔가 자동화 스러우면서도, 관리 포인트가 점점 늘어나는 찝찝한 느낌... 남은건 구성 완료에 대한 약간의 성취감? ㅋ


WRITTEN BY
손가락귀신
정신 못차리면, 벌 받는다.

트랙백  0 , 댓글  0개가 달렸습니다.
secret

CodeBuild error

Server/AWS 2021. 12. 17. 22:56

 

CodeBuild 빌드 중에 발생한 에러 모음이다.

 

빌드 프로젝트 구성 validation

: 빌드 프로젝트 새로 구성시 한번이라도 validation 에 실패하면 재검증시 터무니없는 메시지가 출력됨. 사실 권한 및 정책이 검증과정에서 이미 생성되는데 같은 이름의 권한 및 정책이 존재한다는 메시지가 올바르나... 아무튼 자동 생성된 권한 및 정책을 삭제해도 마찬가지이고... 권한 및 삭제 뒤 빌드 프로젝트를 한번에 새로 구성하면 해결; (한번이라도 검증 실패시 아래 메시지 조우)

 

서비스 역할 이름이 잘못되었습니다. 유효한 문자는 꼬부랑꼬부랑 !@#$ㄲㅉㄸㄲㅉ

 

 

S3 소스 다운로드시 권한 없음

: AmazonS3ReadOnlyAccess 권한 추가로 해결

 

Waiting for DOWNLOAD_SOURCE
AccessDenied: Access Denied
    status code: 403, request id: VX7AKNM69P3N7123, host id: 123y3WpjIvTzVViVzHclfn4F3UfDg4mJA++8BSY6q0jQyEPCWr4cohc0dVJ+q08N/123LMNToEI= for primary source and source version arn:aws:s3:::source-artifact-temp/example/SourceArti/BwUEum1

 

 

buildspec.yml 경로 에러 발생

: 경로 확인으로 해결

 

Phase context status code: YAML_FILE_ERROR Message: stat /codebuild/output/src123816321/src/git-codecommit.ap-northeast-2.amazonaws.com/v1/repos/example/Api/buildspec.yml: no such file or directory

 

 

ecr 로그인 에러

: AmazonEC2ContainerRegistryPowerUser 권한 추가로 해결

 

Running command aws --version
aws-cli/1.20.58 Python/3.9.5 Linux/4.14.252-195.483.amzn2.x86_64 exec-env/AWS_ECS_EC2 botocore/1.21.58

Running command $(aws ecr get-login --region $AWS_DEFAULT_REGION --no-include-email)

An error occurred (AccessDeniedException) when calling the GetAuthorizationToken operation: User: arn:aws:sts::123151105123:assumed-role/exampleCodeBuildServiceRole/AWSCodeBuild-ccf3e123-4123-4123-9ba1-1231fc6797b8 is not authorized to perform: ecr:GetAuthorizationToken on resource: * because no identity-based policy allows the ecr:GetAuthorizationToken action

Command did not exit successfully $(aws ecr get-login --region $AWS_DEFAULT_REGION --no-include-email) exit status 255
Phase complete: PRE_BUILD State: FAILED
Phase context status code: COMMAND_EXECUTION_ERROR Message: Error while executing command: $(aws ecr get-login --region $AWS_DEFAULT_REGION --no-include-email). Reason: exit status 255

 

 

gradle 구문 에러

: 기본 gradle 버전 호환 오류로 스크립트 수정으로 해결 gradle build -> ./gradlew build

 

Running command gradle --version
------------------------------------------------------------
Gradle 5.6.4
------------------------------------------------------------
...
* What went wrong:
An exception occurred applying plugin request [id: 'org.springframework.boot', version: '2.6.0']
> Failed to apply plugin [id 'org.springframework.boot']
   > Spring Boot plugin requires Gradle 6.8.x, 6.9.x, or 7.x. The current version is Gradle 5.6.4

Command did not exit successfully gradle :Api:build exit status 1
Phase complete: BUILD State: FAILED
Phase context status code: COMMAND_EXECUTION_ERROR Message: Error while executing command: gradle :Api:build. Reason: exit status 1

 

 

Dockerfile 경로 에러

: 경로 수정으로 해결 . -> ./AWS/Dockerfile

 

Running command docker build -t $REPOSITORY_URI:latest .
unable to prepare context: unable to evaluate symlinks in Dockerfile path: lstat /codebuild/output/src368940192/src/git-codecommit.ap-northeast-2.amazonaws.com/v1/repos/kps/Dockerfile: no such file or directory

 

 

eks cluster 조회 권한 에러

: AmazonEKSWorkerNodePolicy 권한 수정 및 바인딩 추가로 해결

 

Running command aws eks update-kubeconfig --region ap-northeast-2 --name example

An error occurred (AccessDeniedException) when calling the DescribeCluster operation: User: arn:aws:sts::123151105123:assumed-role/exampleCodeBuildServiceRole/AWSCodeBuild-123e955a-545c-42c6-8d21-67215aef0123 is not authorized to perform: eks:DescribeCluster on resource: arn:aws:eks:ap-northeast-2:123151105123:cluster/example

Command did not exit successfully aws eks update-kubeconfig --region ap-northeast-2 --name example exit status 255
Phase complete: INSTALL State: FAILED
Phase context status code: COMMAND_EXECUTION_ERROR Message: Error while executing command: aws eks update-kubeconfig --region ap-northeast-2 --name example. Reason: exit status 255

 

 

kubectl 권한 에러

: 사용자나 역할에 대한 aws-auth ConfigMap 수정으로 해결

 

Running command kubectl get po -n namespace1
error: You must be logged in to the server (Unauthorized)

Command did not exit successfully kubectl get po -n namespace1 exit status 1
Phase complete: INSTALL State: FAILED
Phase context status code: COMMAND_EXECUTION_ERROR Message: Error while executing command: kubectl get po -n namespace1. Reason: exit status 1
Error from server (Forbidden): error when retrieving current configuration of:
Resource: "apps/v1, Resource=deployments", GroupVersionKind: "apps/v1, Kind=Deployment"
Name: "my-deploy", Namespace: "namespace1"
from server for: "./AWS/example-deployment.yaml": deployments.apps "my-deploy" is forbidden: User "system:node:AWSCodeBuild-fccb1123-1235-49c9-1238-b11cf05bc0c8" cannot get resource "deployments" in API group "apps" in the namespace "namespace1"
Running command kubectl rollout restart -n example-namespace deployment my-deploy
error: failed to patch: deployments.apps "my-deploy" is forbidden: User "system:node:AWSCodeBuild-a0f27123-b1fc-4e12-1e3f-0eac123f5123" cannot patch resource "deployments" in API group "apps" in the namespace "namespace1"

Command did not exit successfully kubectl rollout restart -n namespace1 deployment my-deploy exit status 1
Phase complete: POST_BUILD State: FAILED
Phase context status code: COMMAND_EXECUTION_ERROR Message: Error while executing command: kubectl rollout restart -n namespace1 deployment my-deploy. Reason: exit status 1

 

- codebuild 에 사용된 역할 추가

$ kubectl edit configmap aws-auth -n kube-system

mapRoles: |
...
  - rolearn: arn:aws:iam::123151105123:role/exampleCodeBuildServiceRole
    username: system:node:{{SessionName}}
    groups:
    - system:bootstrappers
    - system:nodes
    - eks-console-dashboard-full-access-group

 

- 클러스터 역할 바인딩 생성

$ vi eks-console-full-access.yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: eks-console-dashboard-full-access-clusterrole
rules:
- apiGroups:
  - ""
  resources:
  - nodes
  - namespaces
  - pods
  verbs:
  - get
  - list
  - patch
- apiGroups:
  - apps
  resources:
  - deployments
  - daemonsets
  - statefulsets
  - replicasets
  verbs:
  - get
  - list
  - patch
- apiGroups:
  - batch
  resources:
  - jobs
  verbs:
  - get
  - list
  - patch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: eks-console-dashboard-full-access-binding
subjects:
- kind: Group
  name: eks-console-dashboard-full-access-group
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: eks-console-dashboard-full-access-clusterrole
  apiGroup: rbac.authorization.k8s.io

 

$ kubectl apply -f eks-console-full-access.yaml
clusterrole.rbac.authorization.k8s.io/eks-console-dashboard-full-access-clusterrole created
clusterrolebinding.rbac.authorization.k8s.io/eks-console-dashboard-full-access-binding created

 

 

codebuild

 


WRITTEN BY
손가락귀신
정신 못차리면, 벌 받는다.

트랙백  0 , 댓글  0개가 달렸습니다.
secret

Exclude log4j2

Daily/Prog 2021. 12. 17. 20:59

log4j

 

ECR 에서 log4j2 사용중인 이미지들 깜빡하고 있었는데 AWS 에서 친절히 메일이 왔다.

 

You are receiving this communication because your account has container images stored in Amazon Elastic Container Registry (ECR). While not all container images are impacted by this CVE, your images may be affected if they are using Java with Apache Log4j in certain configurations. Amazon Inspector scans container images stored in Amazon ECR for software vulnerabilities to generate Package Vulnerability findings and is able to detect this issue in container images. You can turn on enhanced scanning from ECR [2] or enable Inspector from Inspector console to discover this issue in your images[3].

 

계정에 Amazon Elastic Container Registry(ECR)에 저장된 컨테이너 이미지가 있기 때문에 이 통신을 수신하게 되었습니다. 모든 컨테이너 이미지가 이 CVE의 영향을 받는 것은 아니지만 특정 구성에서 Apache Log4j와 함께 Java를 사용하는 경우 이미지가 영향을 받을 수 있습니다. Amazon Inspector는 Amazon ECR에 저장된 컨테이너 이미지에서 소프트웨어 취약성을 스캔하여 패키지 취약성 결과를 생성하고 컨테이너 이미지에서 이 문제를 감지할 수 있습니다. ECR[2]에서 향상된 스캔을 켜거나 Inspector 콘솔에서 Inspector를 활성화하여 이미지에서 이 문제를 발견할 수 있습니다[3].

 

log4j2 취약점이 추가로 계속 발생하고 있다. 2.15 에서 2.16 버전으로 업데이트...

확인하기도 귀찮다. 자꾸 신경쓰이게 하지 말고, logback 쓰고 log4j2 는 그냥 꼬죠.

 

// build.gradle
configurations {
    implementation.exclude group: "org.apache.logging.log4j"
}

 

spring 종속성을 사용한다면,,

 

// gradle
ext['log4j2.version'] = '2.17.2'

 


WRITTEN BY
손가락귀신
정신 못차리면, 벌 받는다.

트랙백  0 , 댓글  0개가 달렸습니다.
secret

TLSv1 deprecated

Daily/Prog 2021. 11. 24. 01:59

20년이 지나도 멈추지 않는 삽질 이야기.

 

WARN: This connection is using TLSv1 which is now deprecated and will be removed in a future release of Connector/J

 

warning 은 신호등에 비유하면 주황색과 같다. 가도 그만 멈추어도 그만인데 난 될수 있으면 멈추는 스타일이다. 그 바람에 또 소중한 시간들을 낭비한다. 위 경고는 TLSv1 / TLSv1.1 이 deprecated 되었으며, 이 프로토콜을 사용한 연결시 MySQL Connector/J Version 8.0.26 버전부터 발생하는 메시지다.

 

참고: https://docs.oracle.com/cd/E17952_01/connector-j-8.0-relnotes-en/news-8-0-26.html

 

3 Changes in MySQL Connector/J 8.0.26 (2021-07-20, General Availability)

3 Changes in MySQL Connector/J 8.0.26 (2021-07-20, General Availability) Version 8.0.26 is the latest General Availability release of the 8.0 series of MySQL Connector/J. It is suitable for use with MySQL Server versions 8.0, 5.7, and 5.6. It supports the

docs.oracle.com

해결은 간단하다. 난 8.0.27 버전을 사용중이었지만 8.0.26 아래 버전으로 다운그레이드 하면 되는데... 이제부터 삽질 시작이다.



Intellij 에서 gradle + java 프로젝트.

모듈은 두개. DB 와 API.

 

// DB module : build.gradle
dependencies {
    ...
    runtimeOnly 'mysql:mysql-connector-java:8.0.25'
    ...
}

// API module : build.gradle
dependencies {
    implementation project(':DB')
}

 

간단하다. DB 모듈에서 MySQL Connector/J 8.0.25 를 정의하고, API 모듈에서 그걸 가져다 썼다. 하지만 경고는 계속해서 나타났다. External Libraries 를 확인해보니 8.0.25 / 8.0.27 두 개 버전이 모두 import 되어 있었다. cache 문제겠거니 하고 기본적인 캐시 삭제 작업들을 시작했다.

 

  • Invalidate Caches -> Invalidate and Restart
  • Project Settings -> Libraries -> MySQL Connector/J 8.0.27 버전 삭제
  • $USER\.gradle\caches 디렉토리 삭제

 

gradle-library-duplicate

 

하지만 이 짓들을 다 해도 MySQL Connector/J 8.0.27 는 계속해서 살아났고 경고가 콘솔에 도배됐다. Find Usages 에서 확인해보니 API 모듈에서 사용중이란다. DB 모듈에서는 8.0.25 를 불러오는데, API 모듈에서 그걸 불러오면 8.0.27 로 변신한다니 이게 대체 무슨...

 

혹시라도 다른 라이브러리에 중복되어 있는지 dependency tree 도 확인해 봤다.

 

 

(DB)  mysql:mysql-connector-java:8.0.25

(API) mysql:mysql-connector-java:8.0.25 -> 8.0.27

 

다른 곳에서 정의 되어 있는건 한개도 없는데 그냥 바뀌어 버린다.ㅋㅋ

 

한참을 삽질한 끝에 밝혀낸 원인은...

gradle 에 정의한 두개의 플러그인 간에 의존성들이 달라 발생한 문제였다.

결국 재정의 했다...

 

dependencies {
    runtimeOnly 'mysql:mysql-connector-java:8.0.25'
    implementation project(':DB')
}

 

 


WRITTEN BY
손가락귀신
정신 못차리면, 벌 받는다.

트랙백  0 , 댓글  0개가 달렸습니다.
secret

Spring Boot REST API 프로젝트에 API 문서 자동화 툴로 뭘 써야 하나...

 

 

Swagger vs Spring rest docs

 

  • Swagger - 적용 난이도 쉬움, 이쁜 UI, API 테스트 기능, 코드 기반
  • Spring rest docs - 적용 난이도 보통, 단순 UI, 테스트 기반

 

장단점이 분명하지만, 내부용으로 후딱 만들어 쓸 것이라면 Swagger. 외부에 제공해야 한다면 정갈해 보이는 Spring rest docs 이 아닐까 싶다.

 

 

문서화를 위한 gradle 구성

 

  • Step 1. 코드 테스트 -> 에러가 발생하지 않으면 해당 api 내용(snippets: asciidoc 파일) 생성.
  • Step 2. Test 로부터 생성된 snippets 을 import 하도록 api 문서 템플릿(asciidoc 파일) 을 생성하고 빌드하여 API 문서(html) 완성.
  • Step 3. 생성된 html 파일을 외부에 노출하도록 static 디렉토리에 복제.

 

plugins {
    id 'org.springframework.boot' version '2.5.6'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id 'java'
    // gradle 7 이상은 org.asciidoctor.convert 대신 org.asciidoctor.jvm.convert 사용
    id 'org.asciidoctor.jvm.convert' version '3.3.2'  // Step 1
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'

bootJar {  // Step 3
    dependsOn asciidoctor
    copy {
        from "${asciidoctor.outputDir}"
        into "${sourceSets.main.output.resourcesDir}/static/docs"
    }
}

asciidoctor {  // Step 2
    sourceDir 'src/main/asciidoc'
    attributes \
        'snippets': file('build/generated-snippets')
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'  // Step 1
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

test {
    useJUnitPlatform()
}

 

이 build.gradle 파일은 가장 기본적인 세팅이므로 추후 익숙해지면 task 를 통합하거나 build 경로를 수정하여 커스터마이징 해서 편하게 쓰면 되겠다. 예를 들면...

 

asciidoctor {
    dependsOn test
    sourceDir 'src/main/asciidoc'
    outputDir "${sourceSets.main.output.resourcesDir}/static/docs"
    attributes \
        'snippets': file('build/generated-snippets')
}

 

3개의 task (단위 Test - html 생성 - html 복사) 를 하나로 통합한 예...

 

아무튼 build.gradle 파일을 수정했으면 JUnit 와 MockMvc 를 사용하여 Test 를 작성한다. (model, controller 생략)
MockMvc, REST Assured 중 서버 구동없이 컨트롤러 단위 테스트가 쉬운 MockMvc 를 사용한다.

 

@WebMvcTest(TestController.class)
@AutoConfigureRestDocs(outputDir = "build/generated-snippets")
public class TestControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void test() throws Exception {

        mockMvc.perform(RestDocumentationRequestBuilders.get("/book/{id}",1).accept(MediaType.APPLICATION_JSON))
                .andDo(print())
                .andExpect(MockMvcResultMatchers.status().isOk())
                .andDo(document("book",
                        pathParameters(
                                parameterWithName("id").description("book unique id")
                        ),
                        responseFields(
                                fieldWithPath("id").description("book unique id"),
                                fieldWithPath("title").description("title")
                        )
                ))
                .andExpect(jsonPath("$.id", is(notNullValue())))
                .andExpect(jsonPath("$.title", is(notNullValue())));
    }
}

 

* 아래 에러 발생시:
urlTemplate not found. If you are using MockMvc did you use RestDocumentationRequestBuilders to build the request?

> pathParameters 을 사용할 때는 MockMvcBuilders.get 대신 RestDocumentationRequestBuilders.get 사용

 

Test 코드에서 document(identifier, ...) 에 기반하여 snippets 의 내용을 구성하게 되며, andExpect 에서 에러가 발생하지 않으면 outputDir 에 snippets 들이 생성된다.

 

curl-request.adoc
http-request.adoc
http-response.adoc
...

 

정상적으로 생성됐다면 이 snippets 들을 불러올 템플릿 asciidoc 파일을 생성한다. (/src/main/asciidoc/)

 

= Document Title
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toc-title: API 명세서
:toclevels: 4

[[api]]

== Book Api
api 에 관련된 설명을 이곳에 적습니다..

include::{snippets}/book/curl-request.adoc[]
include::{snippets}/book/http-request.adoc[]
include::{snippets}/book/path-parameters.adoc[]
include::{snippets}/book/http-response.adoc[]
include::{snippets}/book/response-fields.adoc[]

 

* asciidoc 파일 작성시 참고

https://docs.asciidoctor.org/asciidoc/latest/

https://narusas.github.io/2018/03/21/Asciidoc-basic.html

 

 

Asciidoc 기본 사용법

Asciidoc의 기본 문법을 설명한다

narusas.github.io

 

AsciiDoc Language Documentation :: Asciidoctor Docs

AsciiDoc is a lightweight and semantic markup language primarily designed for writing technical documentation. The language can be used to produce a variety of presentation-rich output formats, all from content encoded in a concise, human-readable, plain t

docs.asciidoctor.org

 

Spring REST Docs는 기본적으로 Asciidoctor 를 사용하지만, Markdown 을 사용할 수도 있다.

간략하게 이런식으로 작성하고 bootJar 를 실행하면 /build/docs/asciidoc/book.html 파일이 생성된 것을 확인할 수 있다.

 

spring-rest-docs

 

bootRun 을 실행하면 해당 파일이 /build/resources/main/static/docs 에 복사되며 http://localhost/docs/book.html 에서 확인 가능.

 

 


WRITTEN BY
손가락귀신
정신 못차리면, 벌 받는다.

트랙백  0 , 댓글  0개가 달렸습니다.
secret