swagger

一、 总体代码文件

需要得依赖文件 pom.xml:

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

创建Swagger2.java：

package com.main;


import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.service.Parameter;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2  // 网上好多放到启动类上面，我放在这儿一样
public class Swagger2 {

    @Bean
    public Docket config() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(false)
                .select().apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .build()
                .globalOperationParameters(setHeaderToken());
    }

    private List<Parameter> setHeaderToken() {
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("Authorization").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        return pars;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("action APIs")
                .description("Demo: User接口文档")
                .version("1.0")
                .build();
    }
}

配置 SwaggerWebMvcConfig：

package com.main;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

@Configuration
public class SwaggerWebMvcConfig extends WebMvcConfigurerAdapter {


    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/js/**").addResourceLocations("classpath:/js/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

示例 UserController.java:

@Api(description = "用户增删改查接口")
@RestController
@RequestMapping("/test")
public class UserContoller {
    private final static Logger LOGGER = LoggerFactory.getLogger(UserContoller.class);
    .......................

二、 详解

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

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

@Api(tags = "一个Controller文件描述信息")
作用在类上，用来标注该类具体实现内容。表示标识这个类是swagger的资源 。 
参数： 
1. tags：可以使用tags()允许您为操作设置多个标签的属性，而不是使用该属性。 
2. description：可描述描述该类作用。

@ApiOperation(value = "接口名称"，notes="接口详细描述信息")

@ApiImplicitParam(name = "name", value = "用户名", required = true, dataType = "String", paramType = "path")： 感觉需要name和value就行 配合绝体的API接口参数

作用在方法上，表示单独的请求参数
参数： 
1. name ：参数名。 
2. value ： 参数的具体意义，作用。 
3. required ： 参数是否必填。 
4. dataType ：参数的数据类型。 
5. paramType ：查询参数类型，这里有几种形式

类型           作用
path        以地址的形式提交数据
query       直接跟参数完成自动映射赋值
body        以流的形式提交 仅支持POST
header      参数在request headers 里边提交
form        以form表单的形式提交 仅支持POST

多个参数:

@ApiImplicitParams({
	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"),
	@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
	})

@ApiResponses(value = {
        @ApiResponse(code = 5000, message = "2001:因输入数据问题导致的报错"),
        @ApiResponse(code = 5001, message = "403:没有权限"),
        @ApiResponse(code = 5002, message = "2500:通用报错（包括数据、逻辑、外键关联等，不区分错误类型）")})

@ApiModelProperty 用于方法，字段 ，表示对model属性的说明或者数据操作更改 

示例：

@ApiModel(value = "User", description = "用户")
    public class User implements Serializable{

    private static final long serialVersionUID = 1546481732633762837L;

    /**
     * 用户ID
     */
    @ApiModelProperty(value = "用户ID", required = true)
    @NotEmpty(message = "{id.empty}", groups = {Default.class,New.class,Update.class})
    protected String id;

    /**
     * code/登录帐号
     */
    @ApiModelProperty(value = "code/登录帐号")
    @NotEmpty(message = "{itcode.empty}", groups = {Default.class,New.class,Update.class})
    protected String itcode;

    /**
     * 用户姓名
     */
    @ApiModelProperty(value = "用户姓名")
    @NotEmpty(message = "{name.empty}", groups = {Default.class,New.class,Update.class})
    protected String name;

参考：https://blog.csdn.net/java_yes/article/details/79183804