2016年10月26日 星期三

SpringMVC + Swagger (Spring Boot)

SpringMVC + Swagger (Spring Boot)
以下將介紹如何在Spring Boot上使用Springfox Swagger2.0

IDE: Eclipse Neon Release (4.6.0)
Plugin: STS

1.新增專案




2.勾選所需功能模組(Web)



下一步


建立專案中



產生的專案目錄結構




3.加入相依jar檔


Maven
<dependency>
    <groupId> io.springfox</groupId >
    <artifactId> springfox-swagger2 </artifactId>
    <version> 2.5.0</version >
</dependency>


Gradle
compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.5.0'



4.建立Swagger配置

org.itri.config.Swagger2SpringBoot.java
@SpringBootApplication
@EnableSwagger2
@ComponentScan ("org.iwlp.controller")
public class Swagger2SpringBoot {
   
    public static void main(String[] args) {
        ApplicationContext ctx = SpringApplication.run(Swagger2SpringBoot. class, args);
      }

      @Bean
      public Docket newsApi() {
          return new Docket(DocumentationType. SWAGGER_2)
                  .apiInfo(apiInfo())
                  .select()
                  .build();
      }
      
      private ApiInfo apiInfo() {
          return new ApiInfoBuilder()
                  .title( "Spring REST Sample with Swagger" )
                  .description( "Spring REST Sample with Swagger" )
                  .version( "2.0")
                  .build();
      }
}



5.建立Controller

org.iwlp.controller.TestController
@RestController
@RequestMapping (value = "/api")
public class TestController {
    private static final Logger log = LoggerFactory.getLogger(TestController. class);
   
    @RequestMapping(method=RequestMethod. GET,value="/hello" )
    public @ResponseBody Object sayHello(
            @RequestParam(required = false, value = "message") String message
            ) {
        log.debug("{}", "message");
        return "Controller HELLO:" + message;
    }
}


6.如何使用SwaggerUI
這時啟動Spring Boot
API DOC:http://ift.tt/2nCDizi
可以看到REST API都使用JSON所描述
並可用呼叫此REST API:http://ift.tt/2nRXcIL

找個SwaggerUI把API DOC網址貼上即可看到專案底下所有REST API


若是本機的SwaggerUI如何呈現
先去Swagger官方網站下載UI




以下範例將SwaggerUI(v2.1.4) dist 資料夾重新命名為apis


重啟Spring Boot後,再用瀏覽器進入SwaggerUI
SwaggerUI : http://127.0.0.1:8080/apis/index.html




可看到自訂的REST APIs



7.如何修改REST API的描述、預設值?

org.iwlp.controller.TestController
@RestController
@RequestMapping (value = "/api")
public class TestController {
    private static final Logger log = LoggerFactory.getLogger(TestController. class);
   
    @RequestMapping(method=RequestMethod. GET,value="/hello" )
    @ApiImplicitParams({
        @ApiImplicitParam(name = "message" , value = "輸入文字訊息", required = true, defaultValue = "Hi,Swagger" ,dataType = "string", paramType = "query")
      })
    public @ResponseBody Object sayHello(
            @RequestParam(value = "message" ) String message
            ) {
        log.debug("{}" , "message");
        return "Controller HELLO:" + message;
    }
}



設定後結果


8.下載專案




參考資料:
Springfox Reference Documentation

Usage of Swagger 2.0 in Spring Boot Applications to document APIs




Tags: Spring, Swagger, Swagger UI, Spring Boot, SpringFox, IFTTT-SYNC
August 26, 2016 at 02:48PM
Open in Evernote