자동으로 RESTful API 샘플을 생성합니다. JSON

Question

Jackson과 Jersey 2.17에 RESTful API가 있습니다. 그들은 모두 JSON 스타일로되어 있으며 잘 작동합니다.

하지만 개발자를 위해 RESTful Docs withJSON 샘플을 생성하고 싶습니다.

그래서 나는 직접 JSON의 샘플 HTML의 문서를 생성,

은 첫째로 나는 ServiceDocGen Maven Plugin을 시도,

일부 받는다는 플러그인을 시도했다. 하지만 @JsonProperty, @JsonIgnore, 과 같은 잭슨 주석은 알지 못합니다. 따라서 JSON 샘플이 정확하지 않습니다.

그런 다음 swagger-jaxrs-maven을 시도했는데 @JsonProperty와 같은 일부 잭슨 주석을 알고 있지만 여전히 @JsonIgnore를 처리 할 수 ​​없습니다. 또한 샘플이 아닌 데이터 스키마에 대한 설명입니다. API가 JSON 문자열을 직접 반환하면 실패합니다.

또한 jaxrs-raml-maven-plugin을 시도했지만 정확하지 않은 샘플을 생성하는 데 JAXB 만 사용할 수 있습니다.

기본적으로 내 요구 사항은 간단하다 :

1. 는 JAX-RS 주석에서 엔드 포인트 URL 및 매개 변수 설명을 생성, 내가 시도 모든 플러그인은 매우 잘했다.

2. 페이로드에서 샘플 JSON을 생성합니다. JSON 샘플 데이터 로직이 맞는지 상관 없지만, 데이터 구조가 정확한지 신경 써야합니다. 따라서 특정 유형의 고정 데이터를 설정하는 것은 괜찮습니다. ServiceDocGen은 항상 문자열에 "text"를 설정합니다. 첫째 자바 객체 트리를 통과, 임의의 형태 보증 된 데이터를 입력 : 나는 그것을 믿을

는 JSON 샘플을 생성하기 때문에 힘든 없습니다. 그런 다음 Jackson 디시리얼라이저를 호출하여 json 데이터를 생성합니다.

하지만 지금까지는 어떤 메이븐 플러그인도이 일을 잘 수행 할 수 없습니다.

의견이 있으십니까?

Answer 1

나는 내 자신의 자바 객체 생성자를 만들어 내 작업을 마쳤습니다. 같은 문제를 가지고 다른 사람들을 돕기 위해, 내가 GitHub의에이 프로젝트에 추가 :이 프로젝트 후

ObjectTreeCreator

을, 나머지 작업은 간단합니다 :

1. 자바 반사 모든 API 방법을 찾을 수
2. 전화 ObjectTreeCreator 자바 반사에 의해 모든 API 방법에
3. 발견 반환 클래스 타입 클래스 타입의 객체를 생성하는
4. Jackson ObjectMapper.writeValueAsString을 호출하여이 객체에서 Json 문자열을 생성합니다.

이제 내 RESTful 의사 생성기가 잘 작동합니다. 약 300 개의 RESTful API를위한 html 문서를 생성하는 데 약 10 초 밖에 걸리지 않습니다.

나는 또한 메이븐 빌드 프로세스에 추가되었습니다. 그래서 때마다 내 빌드 서버가 자동으로 모든 API를 찾아 나를 위해 RESTful 문서를 생성합니다.

생성 된 JSON 구조는 실제 API 응답과 완전히 동일합니다.

그런데 내가 존재한다면 통합 테스트 결과도 사용했습니다.

ObjectTreeCreator는 통합 테스트가없는 경우에만 사용됩니다.

Answer 2

나는 당신이 도구를 찾을 것이라고 생각한다. 가장 좋은 방법은 swagger.json 파일을 작성하고 swagger-ui webjar 종속성을 가져 오는 것입니다.

<dependency> 
    <groupId>org.webjars</groupId> 
    <artifactId>swagger-ui</artifactId> 
    <version>${swagger-ui.version}</version> 
</dependency> 

당신은/사용자 정의 귀하의 swagger.json 파일 또는 어디든지 당신이 원하는에 로컬 호스트 경로를 가리 키도록 자신감-UI 및 하드 코드를의 인덱스 페이지를 재정의 할 수 있습니다.

시간이 제한 사항이 아니라면 리플렉션을 사용하여 JAX-RS 주석을 스캔하고 리버스 엔지니어링하여 변형 json 파일을 생성 할 수있는 메이븐 플러그인을 작성할 수 있습니다. 개인적으로 필자는 단일 json 파일 만 유지하고 해당 파일에서 API 및 모델을 생성하는 것을 선호합니다.

Answer 3

당신은 스프링 restdocs을 시도 할 수 있습니다 :

https://github.com/spring-projects/spring-restdocs

http://docs.spring.io/spring-restdocs/docs/current/reference/html5/

그것은 (RestAssured 또는 MockMvc를 통해) 엔드 포인트의 테스트를 기반으로 문서 미리보기를 생성합니다. 이렇게하면 코드와 문서를 프로그래밍 방식으로 연결할 수 있습니다.

Answer 4

cosbor11의 방향을 반향시키고 코드와 읽을 수있는 워드 프로세서를 동기화하려는 경우 Swagger를 사용하십시오. Phil Hauer가 설명한 서비스 우선 접근법을 지원하는 Swagger Inflector를 확인하십시오.

Inflector를 사용하면 API 사양으로 시작하여 스텁 및 프록시를 생성하거나 서비스 주석을 먼저 시작할 수 있습니다 (코드 주석 당신을위한 자신감 스펙 생성) 아래 참조 : 당신은 자신감/OpenAPISpec 땅에 살고되면

@Api(value = "customers", description = "RESTful API to interact with customer resources.") 
@Path("customers") 
public class CustomerResource { 

    @ApiOperation(value = "Get all customers", notes = "Get all customers matching the given search string.", responseContainer = "List", response = Customer.class) 
    @GET 
    @Path("/") 
    @Produces(MediaType.APPLICATION_JSON) 
    public List<Customer> getCustomers(
      @ApiParam(value = "The search string is used to find customer by their name. Not case sensetive.", required = false, defaultValue = "") @QueryParam("search") String searchString, 
      @ApiParam(value = "Limits the size of the result set", required = false, defaultValue = "50") @QueryParam("limit") int limit) { 
     List<Customer> customers = dao.getCustomers(searchString, limit); 
     return customers; 
    } 
} 

는 자신감-UI를 넘어 (도구의 톤이있다) 정적 문서, 대화 형 샘플을 생성하는 데 도움이 및 사용 사용 가능한 사람이 읽을 수있는 예제를 생성하기 위해 Swagger 스펙에있는 메타 데이터/기본값의 모든 레벨.

당신이 인플 구현에 문제가있는 경우 https://lucybot.com/

https://swaggerhub.com/https://github.com/sourcey/spectacle

• 은 확실히 직접 자신감 사양 및 도구에 @fehguy와 함께 작동 트위터에 @olensmar에게 다가.