1、swagger學(xué)習(xí)

Swagger定義
Swagger同類工具
Swagger和web項目結(jié)合
Swagger在公司項目中如何應(yīng)用

2、Swagger定義

• Swagger官網(wǎng)：http://swagger.io
• GitHub地址：https://github.com/swagger-api
• 官方注解文檔：http://docs.swagger.io/swagger-core/apidocs/index.html
• Swagger-UI地址：https://github.com/swagger-api/swagger-ui
• 概念：
  A Powerful Interface to your API
  Swagger 是一個規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)?？傮w目標(biāo)是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來更新。文件的方法，參數(shù)和模型緊密集成到服務(wù)器端的代碼，允許API來始終保持同步。 Swagger 讓部署管理和使用功能強大的API從未如此簡單。

2.1 Swagger子項目

Swagger子項目

其實swagger是一個比較大的項目，就像spring一樣，他下面有很多模塊，我們現(xiàn)在只需要使用它的UI模。

3、相關(guān)學(xué)習(xí)博客

• 在線Demo: http://petstore.swagger.io
• swagger學(xué)習(xí)分享： http://www.mamicode.com/info-detail-525592.html
• InfoQ視頻：http://www.infoq.com/cn/presentations/use-swagger-create-rest-api-document?utm_source=tuicool&utm_medium=referral
• < http://hao.jobbole.com/swagger/>
• Swagger文檔： http://www.scalatra.org/2.2/guides/swagger.html
• swagger博客-：http://ningandjiao.iteye.com/blog/1948874
• swagger博客二： http://www.itdecent.cn/p/0465a2b837d2
• Swagger博客三： http://javatech.wang/index.php/archives/74/
• Swagger案例: http://petstore.swagger.io/#!/user/createUser

4、swagger和springmvc整合

4.1 依賴管理

 <!-- swagger-mvc -->
    <dependency>
      <groupId>com.mangofactory</groupId>
      <artifactId>swagger-springmvc</artifactId>
      <version>1.0.2</version>
    </dependency>
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>2.4.2</version>
    </dependency>
    <!-- swagger-mvc -->

4.2 Swagger配置

Swagger的配置最終就是配置一個config類，通過Java編碼的方式實現(xiàn)配置：

@Configuration
@EnableSwagger
public class SwaggerConfig {

    private SpringSwaggerConfig springSwaggerConfig;

    /**
     * Required to autowire SpringSwaggerConfig
     */
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
    {
        this.springSwaggerConfig = springSwaggerConfig;
    }

    /**
     * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
     * framework - allowing for multiple swagger groups i.e. same code base
     * multiple swagger resource listings.
     */
    @Bean
    public SwaggerSpringMvcPlugin customImplementation()
    {
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo())
                .includePatterns(".*?");
    }

    private ApiInfo apiInfo()
    {
        ApiInfo apiInfo = new ApiInfo(
                "My Apps API Title",
                "My Apps API Description",
                "My Apps API terms of service",
                "My Apps API Contact Email",
                "My Apps API Licence Type",
                "My Apps API License URL");
        return apiInfo;
    }
}

這個是個模板，里面內(nèi)容可以自己定義，修改基本上是對apiinfo自定義數(shù)據(jù)。
在spring中注入Bean：
<context:component-scan base-package="net.shopin.swagger"/>

swagger基本就算是配置好了，剩下的事情就是接口編寫和展示了。

引入swagger-UI組件
更改項目文檔路徑

更改項目文檔路徑

修改index.html文件中的路徑：默認(rèn)是從連接http://petstore.swagger.io/v2/swagger.json獲取API的JSON,我們改為 http://{ip}:{port}/{projectName}/api-docs 的形式，也就ip:端口號/項目名/api-docs

配置Xml

最后就是對controller的書寫：

@Api(value = "product", description = "商品管理", produces = MediaType.APPLICATION_JSON_VALUE)
@Controller
public class ProductController {

    @Autowired
    private ProductService productService;

    @ApiOperation(value = "獲得商品信息", notes = "獲取商品信息(用于數(shù)據(jù)同步)", httpMethod = "POST", produces=MediaType.APPLICATION_JSON_VALUE)
    @ApiResponses(value = {@ApiResponse(code = 200, message = "商品信息"),
        @ApiResponse(code = 201, message = ErrorType.errorCheckToken + "(token驗證失敗)",  response=String.class),
        @ApiResponse(code = 202, message = ErrorType.error500 + "(系統(tǒng)錯誤)",response = String.class)})
    @RequestMapping(value = RestUrl.getProduct, method = RequestMethod.POST)
    @ResponseBody
    public ResultDTO<Products> getProduct(@ApiParam(value = "json參數(shù)",  required = true) @RequestBody BaseParam param)throws Exception {
        return productService.getProduct(param);
    }
}

當(dāng)然你還需要是配置XML

ぐl(fā)ovefor丶  11:21:08
 <!-- swagger 集成-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>

配置XML的文件

• @API：表示一個開放的API，可以通過description簡明的描述API的功能，produce指定API的mime類型
• 一個@API下，可以有多個@ApiOperation,表示針對該API的CRUD操作，在ApiOperation Annotation中還可以通過value，notes描述該操作的作用，response描述正常情況下該請求返回的對象類型
• 在一個@ApiOperation下，可以通過@ApiResponses描述API操作可能出現(xiàn)的異常情況
• @ApiParam用于描述該API操作接收的參數(shù)類型，value用于描述參數(shù)，required指明參數(shù)是否為必須。
• @ApiModelProperty中，value指定描述，required指明是否為必須

代碼效果

WechatIMG1153.png

WechatIMG1156.png

備注:

swagger 在不同語言中的應(yīng)用,可以直接在網(wǎng)頁上書寫并生成Demo地址