발표할 내용이 무엇인가.
1. 문서 자동화
  1. 문서 작성을 좋아하는 개발자는 없다. 하지 않아도 되면 안할것이다. 그러나 서비스를 운영하고 인수인계를 생각한다면 문서를 만들지 않을 수 없다. 그렇다면 꼭 작성 해야만 하는 문서와 그렇지 않은 문서를 나누어보고 필수로 작성해야하는 문서를 어떻게 개발자가 직접 만들지 않으면서 자동화 시킬수 있을까 생각해보자.
  2. 필수 문서
    1. 시스템 설계도
    2. 디비 구조 및 명세
    3. 비즈니스 로직 명세
    4. API 명세서
    5. Local 세팅 가이드
    6. 서버/포트/방화벽 명세서
  3. 부가 문서
    1. 프로젝트 코드 명세
주제관련 설명
1. 내용을 2파트로 나눠서 진행해야 겠다.
  1. part 1
    1. 문서 자동화가 필요한가?
      1. 서비스를 운영하고 유지보수 하려면 관련 문서를 만들어 두는 것은 필수다.
      2. 하지만 문서를 만드는 것을 좋아할 개발자는 거의 없을 것이다.
      3. 그러니 난 설계하고 코딩만 할테니 문서는 알아서 만들어줬으면 좋겠다 생각할 것이다.
      4. 개발자들이 ci/cd 를 구축하려고 노력하는 이유도 개발에만 집중하기 위해서라고 생각한다.
    2. 무슨 문서를 자동화 할 수 있을까?
      1. 그럼 필수로 작성해야하는 문서들은 무엇이고 이중에 우리가 자동화 할수 있는 것은 무엇일까?
      2. 시스템 설계도, 디비 구조 및 명세서, local 세팅 가이드 등과 같이 아카이빙 해두지 않으며 커뮤니케이션과 서비스 운영에 걸림돌이 될수 있다.
      3. 돌려 돌려 이야기 했지만 우리가 알아 볼것은 api 문서다.
      4. 백에서 개발한 api들에 대한 가이드 문서로써 이 api를 사용하는 백엔드 개발자의 편의를 돕기 위한 목적으로 제작할 수 있으며, 프론트 개발자와 인터페이스를 맞추며 커뮤니케이션 하는데도 활용이 된다.
    3. API 문서 자동화 툴
      1. 가장 대표적인 툴은 두가지가 있다.
      2. spring rest docs, swagger
      3. swagger는 많이 들어 봤을거고, rest docs는 스프링 개발자가 아니면 잘 모를 수도 있다.
      4. 이 발표에서는 spring rest docs를 실습할 것이다.
    4. 왜 spring rest docs인가
      1. 가장 중요한 이유는 내가 spring 개발자고 swagger를 사용해보지 않아 익숙하지 않았기 때문이다.
      2. 더 나아가 각 툴의 지향점이 다르고 rest docs가 나의 개발적 사고와 맞았다는 것도 하나의 이유다.
      3. 비교
        
        API 문서 자동화 툴
        
        API 문서 자동화의 목적은 문서작성에 드는 리소스를 줄이는 것이다.
        
        그렇다면 제품코드 수정하지 않고 테스트 거처 자동으로 문서를 산출하는 rest docs에 매력이 느껴진다.
        
        더구나 테스트를 거쳐야만 문서가 생성이 된다는건 검증된 문서들만 만들어 진다는 것으로 메리트가 있다.
        
        테스트 메커니즘에 대해 익숙하지 않다면 선호하지 않을 수 있지만, 테스트는 꼭 필요한 프로세스며 이를 통에 잃는 것보다 얻는 것이 많다고 생각한다.
        
        반면, Swagger는 러닝커브는 낫지만, API 동작을 테스트하는 용도에 더 특화되어있는 것처럼 보인다.
    5. 실습
      1. mvc 패턴으로 코드를 짜는 과정을 보여준다.
      2. Junit으로 테스트 돌리는 과정을 보여준다.
      3. customizing 한 asciidoc으로 html 파일 생성하는 것 보여준다.
    6. part 2에서 다룰 내용 설명
  2. part 2
    1. 각 필드에 discription 다는 방법 설명
    2. 이또한 자동화 해주는 auto rest docs 설명 및 실습
    3. 이렇게 산출된 문서들을 어떻게 관리할 것인가?
실습

목차