Spring boot中使用springfox来生成Swagger Specification小结

标签：public   swa   website   api文档   github   model   resources   name   variable   

Rest接口对应Swagger Specification路径获取办法：

根据location的值获取api   json描述文件

也许有同学会问，为什么搞的这么麻烦，api json描述文件不就是http://domain:port/v2/api-docs获取的么。

因为如果使用group，api json描述文件就不是上面的情况哦

https://github.com/springfox/springfox-demos/tree/master/boot-swagger

再小结一下swagger与spring之间关系及相关信息：

swagger 官方网站 http://swagger.io/ ，demo示例 http://petstore.swagger.io/
swagger简单来说就是统一定义了api的语义描述(json,yaml)，并提供ui显示，代码自动生成等等，即建立了rest api生态系统。如何生成这些api数据描述文件，大部分语言都有相关实现。

java方面比较好的实现就是springfox
http://springfox.github.io/springfox/
github地址： https://github.com/springfox/springfox 
springfox通过annotation来实现api描述，生成api json描述文件。再交由swagger-ui实现展示。

spring-boot集成：

添加依赖：
gradle依赖：

dependencies {
  compile "io.springfox:springfox-swagger1:${springfoxVersion}"
}

maven依赖：

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

@Configuration
@EnableSwagger2
public class Swagger2Configuration {

@SpringBootApplication
public class CookBookApplication {

swagger默认会把所有的controller生成api描述文件，可以@ApiIgnore参类或者方法进行忽略。

需要显示指定访问方式:get,post,put,delete等。通过save(@RequestBody Country country)，@RequestBody来自动绑定提交的json数据。
domain类通过@ApiModelProperty(hidden = true)忽略不需要提交的属性。

默认swagger集成后会带ui，可以不使用它自带的ui,因为ui的相关静态文件是打包到jar文件，更改不方便。可以下载ui的相关代码进行集成
地址为： https://github.com/swagger-api/swagger-ui。加入相关js后可以进行汉化。swagger-ui提供api文档html描述以及在线测试。
json文件获取地址格式为： http://domain:port/v2/api-docs (如果有group，就不是这个地址了)

http://www.asdtiang.org/2016/02/17/spring-boot-swagger-springfox-%E9%9B%86%E6%88%90/

4.设定访问API doc的路由

在配置文件中，application.yml中声明：

springfox.documentation.swagger.v2.path: /api-docs
这个path就是json的访问request mapping.可以自定义，防止与自身代码冲突。

API doc的显示路由是：http://localhost:8080/swagger-ui.html

如果项目是一个webservice，通常设定home / 指向这里：

@Controller
public class HomeController {

    @RequestMapping(value = "/swagger")
    public String index() {
        System.out.println("swagger-ui.html");
        return "redirect:swagger-ui.html";
    }
}

5.访问

就是上面的了。但是，注意到安全问题就会感觉困扰。首先，该接口请求有几个：

http://localhost:8080/swagger-resources/configuration/ui
http://localhost:8080/swagger-resources
http://localhost:8080/api-docs
http://localhost:8080/swagger-resources/configuration/security
除却自定义的url，还有2个ui显示的API和一个安全问题的API。关于安全问题的配置还没去研究，但目前发现一个问题是在我的一个项目中，所有的url必须带有query htid=xxx,这是为了sso portal验证的时候需要。这样这个几个路由就不符合要求了。

如果不想去研究安全问题怎么解决，那么可以自定ui。只需要将ui下面的文件拷贝出来，然后修改请求数据方式即可。

https://github.com/swagger-api/swagger-codegen/tree/master/samples/server/petstore/springboot

http://www.cnblogs.com/woshimrf/p/5863318.html

http://ju.outofmemory.cn/entry/206015

http://swagger.io/specification/

四、相关注解解读

1. @Api
用在类上，说明该类的作用
@Api(value = "UserController", description = "用户相关api")

2. @ApiOperation
用在方法上，说明方法的作用
@ApiOperation(value = "查找用户", notes = "查找用户", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

3 @ApiImplicitParams
用在方法上包含一组参数说明

4. @ApiImplicitParam
用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
paramType：参数放在哪个地方
header–>请求参数的获取：@RequestHeader
query–>请求参数的获取：@RequestParam
path（用于restful接口）–>请求参数的获取：@PathVariable
body（不常用）
form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的意思
defaultValue：参数的默认值

@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "唯一id", required = true, dataType = "Long", paramType = "path"),
})

5. @ApiResponses
用于表示一组响应

6. @ApiResponse
用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如”请求参数没填好”
response：抛出异常的类

@ApiResponses(value = {  
          @ApiResponse(code = 400, message = "No Name Provided")  
  })

7. @ApiModel
描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModel(value = "用户实体类")

8. @ApiModelProperty
描述一个model的属性
@ApiModelProperty(value = "登录用户")

五、 和Swagger UI的集成（Spring boot 集成springfox后，默认就带了swagger-ui.html了，不需要此操作。如果想对界面进行定制，则需要）
首先，从github swagger-ui 上下载Swagger-UI, 把该项目dist目录下的内容拷贝到项目的resources的目录public下。

https://github.com/JavaUsers/xiaomo-info-java/tree/master/website
https://xiaomo.info/2016/JavaSpringBootSwaggerUi/

Spring boot中使用springfox来生成Swagger Specification小结

标签：public   swa   website   api文档   github   model   resources   name   variable   

原文地址：http://www.cnblogs.com/softidea/p/6223844.html