Eclipse MicroProfile OpenAPI의 with WildFly Swarm을 시도했습니다.

8430 단어 WildFly-SwarmJavaEEOpenAPIJava

모티프


WildFry Swarm 2018.3.3에 Eclipse Micro Profile 1.3이 추가되었기 때문에 Micro Profile OpenAPI 1.0을 시험해 보고 싶습니다. 이것은 마이크로소프트 Profile 1.3의 규격입니다.

OpenAPI Specification은 이전 Swagger Specification


OpenAPI Specification(OAS)은 이전에는 Swagger Specification으로, SmartBear 회사의 제품Swagger 고유의 물건을 OpenAPI Initiative(Linux Fundation의 공동 프로젝트)에 기증해 공개된 규격이 됐다.
OpenAPI의 규격에 맞는 YAML이나 JSON이 있다면 REST API의 참고를 제작할 수도 있고 언어별 REST API를 생성할 수도 있다.

미니 파일 OpenAPI 1.0은


이번에 MS 프로필 1.3에 추가된 MS 프로필 OpenAPI 1.0에는 JAX-RS Resource가 제작됐으며, 사양은 YAML 또는 JSON으로 자동 제공된다.
애초 디자인(문서)이 우선이었더라도 OAS의 YAML을 통해 API의 규격을 결정하고 코드로 떨어진 뒤 규격을 변경했더라도 API 문서에 직접 반영할 수 있어 규격 재작성은 하지 않는다는 것이다.

해야 할 일.했던 일.


이번엔 코딩이 우선인 와일드플라이 스warm 2018.3.3으로 JAX-RS Resource를 제작해 오픈API 표준규격(YAML) 생성 여부를 확인한다.

공정 생성


http://wildfly-swarm.io/generator/에 액세스하고 Dependencies 형식MicroProrfile을 입력할 때 프롬프트MicroProfile OpenAPI Fraction 때문에 "Generate Project"를 선택하면 Micro Profile을 사용할 수 있는 WildFly Swarm 프로젝트(zip 파일)를 다운로드합니다.

구축 및 시작


다운로드한 zip을 펼치면 구축만 하면 이미 JAX-RS의 앱으로 작동할 수 있다.
다운로드한 zip 확장 및 구축
unzip demo.zip
cd demo
mvn package
구축된 target 산하에 사항이 있는 JAR 파일(Uber JAR)이 완성되어 자바 명령으로 시작합니다.
구축된 응용 프로그램 시작
java -jar target/demo-swarm.jar

시작한 애플리케이션에 액세스하기


방문http://localhost:8080/hello시 획득Hello from WildFly Swarm!
$ curl -i http://localhost:8080/hello                                                                                                  [03/24 15:15]
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: text/plain;charset=UTF-8
Content-Length: 25
Date: Sat, 24 Mar 2018 06:17:20 GMT

Hello from WildFly Swarm!
실제로 이때 API 규격이 공개됐다.
http://localhost:8080/openapi에 액세스하면 OpenAPI Specification의 YAML 형식에 맞는 파일을 얻을 수 있습니다.
이것은 API의 규격서다.
$ curl -i http://localhost:8080/openapi
---
openapi: 3.0.1
info:
  title: MicroProfile OpenAPI with WildFly Swarm
  description: This is a sample server for a MicroProfile OpenAPI.
  version: 1.0.0-SNAPSHOT
paths:
  /hello:
    get:
      responses:
        200:
          content:
            text/plain: {}

알기 쉬운 페이지를 만들다


이렇게 되면 API 규격으로 못 읽는 것도 아니지만, 사람에게 좋지 않아 문서로 잘 만들어 읽기로 했다.
다방면의 조사를 통해 ReDoc가 비교적 좋은 것 같다.Docker Engine의 API 참조에서도 이것을 사용했다.

JAX-RS 경로 변경


HTML을 설정하고 싶지만 기본 루트 경로가 JAX-RS 경로여서 /api로 변경되었습니다.
JaxRsActivator.java
// package, import は省略

@ApplicationPath("api")
public class JaxRsActivator extends Application {

}
이로써 /hello의 자원은 /api/hello으로 바뀌었다.

ReDoc의 HTML 만들기


ReDoc의 READMEmd에도 다음과 같이 HTML 파일을 배치한다고 쓰여 있습니다.
src/main/webapp/index.html
<!DOCTYPE html>
<html>
    <head>
        <title>ReDoc</title>
        <!-- needed for adaptive design -->
        <meta charset="utf-8"/>
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
        <!--
        ReDoc doesn't change outer page styles
        -->
        <style>
            body {
                margin: 0;
                padding: 0;
            }
        </style>
    </head>
    <body>
    <!-- ここで /openapi を参照するようにしてあげる！ -->
    <redoc spec-url='/openapi'></redoc>
    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
</body>
</html>
그리고 설사 짓고 시동을 걸면
.
http://localhost:8080/api/hello에서 JAX-RS 리소스 제공
http://localhost:8080/openapi에서 OpenAPI Specification 표준에 부합되는 YAML을 볼 수 있습니다.
http://localhost:8080/에서 멋진 API 문서가 완성되었습니다!

제목, 라이선스, 접촉정보 등 다양한 정보src/main/resources/META-INF/openapi.json를 설정OpenAPI Specification 형식에 따라에서 수정하려면 페이지도 반영된다.

문서를 더욱 충실하게 하기 위해


Micro Profile OpenAPI에는 다양한초대하다이 준비돼 있으며, JAX-RS Resource에 적절하게 설치되면 OpenAPI Specification 호환 정보를 첨부할 수 있다.
또한 ReDoc에 대응하는Extension 설정을 통해 API를 생성하는 클라이언트용 샘플 코드를 추가할 수 있는 기능이나 POSTJSON의 Example 등 정보를 추가할 수 있다.

데모용 코드


기릿허브https://github.com/sightseeker/wildfly-swarm-mp-demo에 올라왔기 때문에 바로 해보고 싶은 분들은 이걸로 하세요.

Files


파일은 이것뿐입니다.
├── pom.xml
└── src
    └── main
        ├── java/com/sightseekerstudio/wildflyswarmmpdemo/rest
        │   ├── HelloWorldEndpoint.java
        │   └── JaxRsActivator.java
        ├── resources
        │   └── META-INF
        │       └── openapi.json
        └── webapp
            └── index.html
SqoopConfiguration 객체 소스 분석
PDF 서버(Figma 템플릿용) STEP 1

좋은 웹페이지 즐겨찾기

개발자 우수 사이트 수집

개발자가 알아야 할 필수 사이트 100선 추천 우리는 당신을 위해 100개의 자주 사용하는 개발자 학습 사이트를 정리했습니다
best100-homepage