Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。

官网：springfox.github.io/springfox/d…

构建spring-web或者springboot-web项目：

1.1 引入依赖

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

1.2 配置Swagger 2

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerApp {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kenny.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("learning Swagger")
                .description("for swagger only")
                .contact(new Contact("swagger-study","https://localhost:8080","myEmail@gmail.com"))
                .version("0.0.1")
                .build();
    }
}

1.3 访问Swagger ui

<http://localhost:8080/swagger-ui.html />

2. Swagger核心注解介绍

import com.kenny.bean.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import org.springframework.web.bind.annotation.*;

@Api(tags = "my Api")
@RestController
@RequestMapping("/user")
public class UserController {
    @ApiOperation(value = "根据id查询用户信息")
    @ApiImplicitParam(name = "id",value = "user id", required = true,dataType = "Integer")
    @ApiResponse(response = User.class,code = 200,message = "return User")
    @GetMapping("/{id}")
    public User getUser(@PathVariable("id") Integer id) {
        System.out.println("getUser: " + id);
        User user = new User();
        user.setId(id);
        user.setName("name-" + id);
        return user;
    }
}