Springboot整合swagger2.8.0 線上API文檔

Swagger 是一個規範和完整的架構，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。用處：

1.自動生成線上文檔

2.接口測試

整合過程

添加swagger2依賴

<dependency>  
            <groupId>io.springfox</groupId>  
            <artifactId>springfox-swagger2</artifactId>  
            <version></version>
        </dependency>  
        <dependency>  
            <groupId>io.springfox</groupId>  
            <artifactId>springfox-swagger-ui</artifactId>  
            <version></version>
        </dependency>
           

建立swagger配置類

/**
 * Swaggers 配置
 */
@Configuration
//啟用swagger,生産環境請注釋掉
@EnableSwagger2
public class Swaggers {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enableUrlTemplating(true)
                .select()
                // 掃描所有有注解的api，用這種方式更靈活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 首頁描述
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2建構RESTful APIs")
                .description("更多Spring Boot相關文章請百度：http://www.baidu.com")
                .termsOfServiceUrl("http://www.baidu.com/")
                .build();
    }
}
           

@Configuration注解，讓Spring來加載該類配置。再通過@EnableSwagger2注解啟用Swagger2

線上文檔添加

@RestController
@RequestMapping(value = "/users")
@Api(value = "使用者測試資訊", tags = {"使用者測試相關接口"})//swagger控制器說明注解
public class UserController {
     /**
     * * 入參是對象,使用預設參數paramType = "body"
     * ApiIgnore()用于類，方法，方法參數
     * 表示這個方法或者類被忽略,不被顯示在swagger頁面上
     * @param resp
     * @param id
     * @param user
     * @return
     */
    @ApiOperation(value = "更新使用者詳細資訊", notes = "根據url的id來指定更新對象，并根據傳過來的user資訊來更新使用者詳細資訊")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "Long")
    })
    @RequestMapping(value = "/{id}", method = RequestMethod.PUT)
    public String putUser(@ApiIgnore ApiReturnInfo resp,@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }

}
           

添加swagger注解之後，啟動springboot服務，通路浏覽器http://localhost:8080/swagger-ui.html 就可以看到線上的API文檔。

swaggerUI通路404解決

重新指定靜态資源，把swagger-ui.html頁面加入

@Configuration
public class ServletContextConfig extends WebMvcConfigurationSupport {
    /**
     * 重新指定靜态資源
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }

}
           

使用體會

感覺線上文檔生成倒是很好用，但swagger自帶的接口測試不怎麼好用，需要注意很多，

1、在接收參數的地方需要使用@RequestBody，才能接收，這點需要注意下；使用過springboot的同學都清楚，接收參數不需要加注解，就能接收。

2、如果存在多個參數類型，自定義對象及基礎類型，這種資料即使使用@RequestBody，背景也是接收失敗。目前還沒找到解決方案，暫時隻使用swagger2的線上文檔，調試還是使用postman，汗顔…. ps:有解決方案的小夥伴請留言，不勝感激

完整demo請參考:springboot-swagger2-demo

swagger常用注解說明

• @Api()用于類；

  表示辨別這個類是swagger的資源

• @ApiOperation()用于方法；

  表示一個http請求的操作

• @ApiParam()用于方法，參數，字段說明；

  表示對參數的添加中繼資料（說明或是否必填等）

• @ApiModel()用于類

  表示對類進行說明，用于參數用實體類接收

• @ApiModelProperty()用于方法，字段

  表示對model屬性的說明或者資料操作更改

• @ApiIgnore()用于類，方法，方法參數

  表示這個方法或者類被忽略

• @ApiImplicitParam() 用于方法

  表示單獨的請求參數

• @ApiImplicitParams() 用于方法，包含多個 @ApiImplicitParam