Spring Boot + Swagger

http://springfox.github.io/springfox/docs/current/#customizing-the-swagger-endpoints

一、什么是Swagger？

Swagger: 一个描述Restful service规范

可以在界面上测试RestfulService

swagger-ui: 用来显示API文档
swagger-editor：就是一个在线编辑文档说明文件（swagger.json或swagger.yaml文件）的工具，以方便生态中的其他小工具（swagger-ui）等使用
swagger-validator: 这个小工具是用来校验生成的文档说明文件是否符合语法规定的。用法非常简单，只需url地址栏，根路径下加上一个参数url，参数内容是放swagger说明文件的地址。即可校验。
swagger-codegen: 代码生成器，脚手架。可以根据swagger.json或者swagger.yml文件生成指定的计算机语言指定框架的代码。

二、Swagger 和 Springfox-Swagger

What is the relationship between swagger-ui and springfox-swagger-ui?
    Swagger Spec is a specification.
    Swagger Api - an implementation of that specification that supports jax-rs, restlet, jersey etc.
    Springfox libraries in general - another implementation of the specification focused on the spring based ecosystem.
    Swagger.js and Swagger-ui - are client libraries in javascript that can consume swagger specification.
    springfox-swagger-ui - the one that you’re referring to, is just packaging swagger-ui in a convenient way so that spring services can serve it up.

翻译下来就是：
swagger-ui 和 springfox-swagger-ui 的关系是？
    Swagger Spec 是一个规范。
    Swagger Api 是 Swagger Spec 规范的一个实现，它支持 jax-rs, restlet, jersey 等等。
    Springfox libraries 是 Swagger Spec 规范的另一个实现，专注于 spring 生态系统。
    Swagger.js and Swagger-ui 是 javascript 的客户端库，能消费该规范。
    springfox-swagger-ui 仅仅是以一种方便的方式封装了 swagger-ui ，就是可以显示文档内容

三、Springboot 与Swagger集成

1. 增加下面maven 引用

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

2. 增加一个Swaagger configuration

package com.example.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;@Configuration
public class Swagger2UiConfiguration extends WebMvcConfigurerAdapter
{@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("org.springframework.boot")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("springboot利用swagger构建api文档").description("简单优雅的restful风格，http://XX").termsOfServiceUrl("http://XXx").version("1.0").build();}}

3.Spring Boots Application 类增加 @EnableSwagger2

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;import springfox.documentation.swagger2.annotations.EnableSwagger2;@SpringBootApplication
@EnableSwagger2
public class UserApplication1 {public static void main(String[] args) {SpringApplication.run(UserApplication1.class, args);}
}

4. 在Controller 中增加相对应的API注释

package com.example.demo;import java.util.concurrent.atomic.AtomicLong;import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;@RestController
public class GreetingController {private static final String template = "Hello, %s!";private final AtomicLong counter = new AtomicLong();@ApiOperation(value="获取Greeting info", notes="根据name获取greeting info")@ApiImplicitParam(name = "name", value = "用户名", required = true, dataType = "String", paramType = "path")@RequestMapping("/greeting")public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {return new Greeting(counter.incrementAndGet(), String.format(template, name));}
}

部署启动服务器

访问： http://localhost:8080/swagger-ui.html#

四、Swagger注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数