Spring Boot + Swagger

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

一、什么是Swagger？

Swagger:  一个描述Restful service规范

               可以在界面上测试RestfulService

1. swagger-ui: 用来显示API文档
2. swagger-editor： 就是一个在线编辑文档说明文件（swagger.json或swagger.yaml文件）的工具，以方便生态中的其他小工具（swagger-ui）等使用
3. swagger-validator: 这个小工具是用来校验生成的文档说明文件是否符合语法规定的。用法非常简单，只需url地址栏，根路径下加上一个参数url，参数内容是放swagger说明文件的地址。即可校验。
4. 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 
{
		@Bean
		public 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：多个请求参数