Swagger：Springboot配置swagger

step1：安装依赖包（二选一）

<!-- https://mvnrepository.com/artifact/com.spring4all/swagger-spring-boot-starter -->
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.1.RELEASE</version>
</dependency>

或者添加另外的依赖。以下的依赖需连个都添加。

<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>

step2：swagger配置

在application.yml里配置swagger所需信息

swagger:
  enabled: true
  base-package: 'com.example.demo.controller'
  title: 'spring-boot-swagger-demo'
  description: '基于Swagger构建的SpringBoot RESTApi 文档'
  version: '1.0'
  contact:
    name: 'Jcsim'
    url: 'https://blog.csdn.net/weixin_38676276'
    email: '[email protected]'

 创建Swagger配置类

package com.example.demo.config;

import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
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.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

/**
 * Created with IntelliJ IDEA.
 *
 * @Author: Jcsim
 * @Date: 2020/10/24 15:30
 * @Description:
 */
@Slf4j
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Value("${swagger.enabled}")
    private boolean SwaggerSwitch;
    @Value("${swagger.base-package}")
    private String basePackage;
    @Value("${swagger.title}")
    private String title;
    @Value("${swagger.description}")
    private String description;
    @Value("${swagger.version}")
    private String version;
    @Value("${swagger.contact.name}")
    private String name;
    @Value("${swagger.contact.url}")
    private String url;
    @Value("${swagger.contact.email}")
    private String email;
    @Bean
    public Docket createRestApi() {
        log.info("======================== 当前环境是否开启Swagger：" + SwaggerSwitch + " ========================");
        return new Docket(DocumentationType.SWAGGER_2)
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts())
                //配置是否启用Swagger，如果是false，在浏览器将无法访问，默认是true
                .enable(SwaggerSwitch)
                //apiInfo： 添加api详情信息，参数为ApiInfo类型的参数，这个参数包含了第二部分的所有信息比如标题、描述、版本之类的，开发中一般都会自定义这些信息
                .apiInfo(apiInfo())
                .select()
                //apis： 添加过滤条件,
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
//        Contact contact = new Contact("Jcsim", "http://www.Jcsim.cn", "[email protected]");
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .contact(new Contact(name, url, email))
                .version(version)
                .build();
    }

}

step3： 在controller方法添加注解

package com.example.demo.controller;

import io.swagger.annotations.*;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.Map;

/**
 * Created with IntelliJ IDEA.
 *
 * @Author: Jcsim
 * @Date: 2020/10/19 11:32
 * @Description:
 */
//@RestController
@Api(tags = "测试")
@RestController
@RequestMapping("/sys")
public class HelloController {
    @ApiOperation("测试swagger")
//@ApiImplicitParams：多个请求参数
    @ApiImplicitParams(
            value = {
                    @ApiImplicitParam(name = "key", value = "参数1", required = true, dataType = "String", defaultValue = "测试"),
                    @ApiImplicitParam(name = "key3", value = "参数2", required = true, dataTypeClass = java.lang.Integer.class, defaultValue = "1")
            }
    )
    @GetMapping("/hello")
    public Object sayHello(String key, Integer key3){
        Map<String,Object> maps = new HashMap<>();
        maps.put("key",key);
        maps.put("key3",key3);
        return maps;
    }

    @GetMapping("/test")
    public String hello(){
        return "test";
    }

    @GetMapping("/test2")
    public String hello2(){
        return "test222222222";
    }


    @GetMapping("/test25")
    public String hello25(){
        return "test22222222255555555555555555555555";
    }

}

step4：启动项目 ，访问http://localhost:8080/swagger-ui.html

 

---

前后端分离，加入token请求头

step1：在swagger配置类里添加请求头

（完整的配置类）

package com.example.demo.config;

import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
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.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

/**
 * Created with IntelliJ IDEA.
 *
 * @Author: Jcsim
 * @Date: 2020/10/24 15:30
 * @Description:
 */
@Slf4j
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Value("${swagger.enabled}")
    private boolean SwaggerSwitch;
    @Value("${swagger.base-package}")
    private String basePackage;
    @Value("${swagger.title}")
    private String title;
    @Value("${swagger.description}")
    private String description;
    @Value("${swagger.version}")
    private String version;
    @Value("${swagger.contact.name}")
    private String name;
    @Value("${swagger.contact.url}")
    private String url;
    @Value("${swagger.contact.email}")
    private String email;
    @Bean
    public Docket createRestApi() {
        log.info("======================== 当前环境是否开启Swagger：" + SwaggerSwitch + " ========================");
        return new Docket(DocumentationType.SWAGGER_2)
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts())
                //配置是否启用Swagger，如果是false，在浏览器将无法访问，默认是true
                .enable(SwaggerSwitch)
                //apiInfo： 添加api详情信息，参数为ApiInfo类型的参数，这个参数包含了第二部分的所有信息比如标题、描述、版本之类的，开发中一般都会自定义这些信息
                .apiInfo(apiInfo())
                .select()
                //apis： 添加过滤条件,
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
//        Contact contact = new Contact("Jcsim", "http://www.Jcsim.cn", "[email protected]");
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .contact(new Contact(name, url, email))
                .version(version)
                .build();
    }

    /**
     * swagger加入全局Authorization header 将在ui界面右上角新增token输入界面
     * @return
     */
    private List<ApiKey> securitySchemes() {
        ApiKey apiKey = new ApiKey("Authorization", "token", "header");
        ArrayList arrayList = new ArrayList();
        arrayList.add(apiKey);
        return arrayList;
    }

    /**
     * 在Swagger2的securityContexts中通过正则表达式，设置需要使用参数的接口（或者说，是去除掉不需要使用参数的接口），
     * 如下列代码所示，通过PathSelectors.regex("^(?!auth).*$")，
     * 所有包含"auth"的接口不需要使用securitySchemes。即不需要使用上文中设置的名为“Authorization”，
     * type为“header”的参数。
     *
     */
    private List<SecurityContext> securityContexts() {
        SecurityContext build = SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.any())
                .build();
        ArrayList arrayList = new ArrayList();
        arrayList.add(build);
        return arrayList;
    }

    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        SecurityReference authorization = new SecurityReference("Authorization", authorizationScopes);
        ArrayList arrayList = new ArrayList<>();
        arrayList.add(authorization);
        return arrayList;
    }
}

step2：方位页面 http://localhost:8080/swagger-ui.html 

此时会增加Authorize

step3：点击"Authorize"，在“value”中输入token值“aaa”

step4：测试接口，可以看到header成功加入了token

---

---

Swagger常用注解

在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下： 

@Api：修饰整个类，描述Controller的作用 

@ApiOperation：描述一个类的一个方法，或者说一个接口 @ApiParam：单个参数描述 

@ApiModel：用对象来接收参数 

@ApiModelProperty：用对象接收参数时，描述对 象的一个字段 @ApiResponse：HTTP响应其中1个描述 

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用 该注解忽略这个API

@ApiError ：发生错误返回的信息 

@ApiImplicitParam：一个请求参数 

@ApiImplicitParams：多个请求参数

@ApiImplicitParam属性：