springboot 集成Swagger2

一、Swagger简介

Swagger 是最流行的 API 开发工具，它遵循 OpenAPI Specification（OpenAPI 规范，也简称 OAS）。
Swagger 可以贯穿于整个 API 生态，如 API 的设计、编写 API 文档、测试和部署。
Swagger 是一种通用的，和编程语言无关的 API 描述规范。

二、应用场景

• 如果你的 RESTful API 接口都开发完成了，你可以用 Swagger-editor 来编写 API 文档（ yaml 文件 或 json 文件），然后通过 Swagger-ui 来渲染该文件，以非常美观的形式将你的 API 文档，展现给你的团队或者客户。
• 如果你的 RESTful API 还未开始，也可以使用 Swagger ，来设计和规范你的 API，以 Annotation （注解）的方式给你的源代码添加额外的数据。这样，Swagger 就可以检测到这些数据，自动生成对应的 API 文档。

三、Swagger工具

Swagger提供了多种工具，帮助解决api的不同的情况下的问题

Swagger-ui 是一套 HTML/CSS/JS 框架，用于渲染 Swagger 文档，以便提供美观的 API 文档界面。也就是说，Swagger-ui 是一个 UI 渲染工具。

三、集成步骤

1、配置Maven依赖

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

2、Swagger配置类,还可以统一添加请求头

/**
 * Copyright (c) 2016-2019 人人开源 All rights reserved.
 *
 * https://www.renren.io
 *
 * 版权所有，侵权必究！
 */

package com.example.demo.config;


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.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.List;

import static com.google.common.collect.Lists.newArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {

    //head请求头参数配置start
    	ParameterBuilder tokenPar = new ParameterBuilder();
    	List<Parameter> pars = new ArrayList<Parameter>();
    	tokenPar.name("x-access-token").description("令牌").modelRef(new 
        ModelRef("string")).parameterType("header").required(false).build();
    	pars.add(tokenPar.build());
	//head请求头参数配置end

        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //加了ApiOperation注解的类，才生成接口文档
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            //包下的类，才生成接口文档
            //.apis(RequestHandlerSelectors.basePackage("io.renren.controller"))
            .paths(PathSelectors.any())
            .build()
            .globalOperationParameters(pars)        //添加全局head请求头参数配置
            .securitySchemes(security())            //添加Authorize配置
            .securityContexts(securityContexts());  //添加Authorize配置
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("人人开源")
            .description("renren-api文档")
            .termsOfServiceUrl("https://www.renren.io")
            .version("4.0.0")
            .build();
    }

    /**
     * 配置右上角的Authorize
     */
    private List<ApiKey> security() {
        return newArrayList(
                new ApiKey("Authorization", "Authorization", "header"));
    }

    /**
     * 配置右上角的Authorize
     */
    private List<SecurityContext> securityContexts() {
        return newArrayList(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build()
        );
    }

    /**
     * 配置右上角的Authorize
     */
    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return newArrayList(
                new SecurityReference("Authorization", authorizationScopes));
    }

}

效果：配置完之后点击右上角的Authorize，弹出认证窗口之后输入请求token，这样之后的每次请求的请求头都会带有token认证信息

3、在Controller中使用Swagger注解

@RestController
@Api(tags="用户管理")
public class UserController {

    @GetMapping("/user/list")
    @ApiOperation("列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", paramType = "query", required = true, dataType="string"),
             @ApiImplicitParam(name = "password", value = "密码", paramType = "query",required = true, dataType="string")
            })
    public String list(String username,String password)
    {
        System.out.println(username);
        System.out.println(password);
        return "success";
    }
}

注解说明

• @Api：用在类上，说明该类的作用。
• @ApiOperation：注解来给API增加方法说明。
• @ApiImplicitParams : 用在方法上包含一组参数说明。
• @ApiImplicitParam：用来注解来给方法入参增加说明。
• @ApiResponses：用于表示一组响应
• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
• @ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
• @ApiModelProperty：描述一个model的属性

4、输入网址localhost:8080/swagger-ui.html，测试api