效果图

一：swagger是什么？

1、是一款让你更好的书写API文档的规范且完整框架。

2、提供描述、生产、消费和可视化RESTful Web Service。

3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

二：使用

方法一：使用第三方依赖（最简单的方法）

1、在pom.xml文件中添加第三方swagger依赖（）

	<dependency>
		<groupId>com.spring4all</groupId>
		<artifactId>swagger-spring-boot-starter</artifactId>
		<version>1.7.0.RELEASE</version>
	</dependency>

2、在Spring Boot项目的启动类上添加@EnableSwagger2Doc注解，就可以直接使用啦。
3、https://github.com/SpringForAll/spring-boot-starter-swagger这是GitHub上这个swagger依赖实现的项目，里面有详细的讲解。

方法二：使用官方依赖+配置类

1、在pom.xml文件中添加swagger相关依赖

        <!--        swagger-->
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

第一个是API获取的包，第二是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。
2、swagger的configuration

需要特别注意的是swagger scan base package,这是扫描注解的配置，即你的API接口位置。

package com.bennyrhys.swagger.config;


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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Config { 
    @Bean
    Docket docket() { 
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bennyrhys.swagger"))
                .paths(PathSelectors.any())
// 基本网站配置信息
                .build().apiInfo(new ApiInfoBuilder()
                        .description("接口文档描述信息")
                        .title("项目接口文档")
                        .contact(new Contact("bennyrhys", "htpps://xxx", "bennyrhys@163.com"))
// .version("v1.0.0")
                        .license("v1.0.0-Apache2.0")
                        .build());
    }
}

具体使用

实体类

描述、必填、隐藏

2.x版本

@ApiModel(description = "用户信息描述类")
public class User { 
    @ApiModelProperty(value = "用户id")
    private Integer id;
    @ApiModelProperty(value = "用户名")
    private String username;
    @ApiModelProperty(value = "用户地址")
    private String address;

1.x版本
@ApiModelProperty(value = "Topic列表", required = false, hidden = true)

controller

建议不加value
加operation的描述方法
加是否必传

    // 可以不展示此接口
// @ApiIgnore

查询，是否必要

    
    // 方法 方法描述
    @ApiOperation(value = "查询用户",notes = "根据用户id查询用户 ")
    // 参数 参数描述 参数必填【针对swagger】
// @ApiImplicitParam(name = "id", value = "用户id", required = true, defaultValue = "99")
    @GetMapping("/user")
    public User getUserById(Integer id) { 
        User user = new User();
        user.setId(id);
        return user;
    }

删除，返回值

    @ApiOperation(value = "删除用户",notes = "根据用户id删除用户")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, defaultValue = "99")
    @ApiResponses({ 
            @ApiResponse(code = 200, message = "删除成功"),
            @ApiResponse(code = 500, message = "删除失败")
    })

更新，多参数

    
    @ApiImplicitParams({ 
            @ApiImplicitParam(name = "id", value = "用户id", required = true, defaultValue = "99"),
            @ApiImplicitParam(name = "username", value = "用户名", required = true, defaultValue = "bennyrhys")
    })
    @ApiOperation(value = "更新用户",notes = "根据用户id更新用户名")

待完善

权限
响应