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
{
@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:多个请求参数