Swagger ： Springboot 配置 swagger

etapa 1: Instale os pacotes dependentes (escolha um dos dois)

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

Ou adicione outra dependência. As seguintes dependências precisam ser adicionadas.

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

 

etapa 2: configuração swagger

Configure as informações exigidas pelo swagger em application.yml

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

 Criar classe de configuração 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();
    }

}

 

passo 3: Adicionar anotações ao método do controlador

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";
    }

}

etapa 4: inicie o projeto, visite http: // localhost: 8080 / swagger-ui.html

 

---

Separe as extremidades frontal e posterior, adicionando o cabeçalho da solicitação de token

etapa 1: adicionar o cabeçalho da solicitação na classe de configuração swagger

(Aula de configuração completa)

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

etapa 2: página de direção  http: // localhost: 8080 / swagger-ui.html 

Autorizar será adicionado neste momento

passo 3: Clique em "Autorizar" e insira o valor do token "aaa" em "valor"

etapa 4: teste a interface, você pode ver que o cabeçalho foi adicionado com sucesso ao token

 

---

---

 

Anotações comuns de Swagger

A interface Swagger pode ser gerada adicionando anotações Swagger à classe Java. Anotações Swagger comumente usadas são as seguintes: 

@Api: Decore a classe inteira e descreva a função do Controlador 

@ApiOperation: descreve um método de uma classe ou uma interface @ApiParam: descrição de um único parâmetro 

@ApiModel: Use objetos para receber parâmetros 

@ApiModelProperty: Ao usar um objeto para receber parâmetros, descreva um campo do objeto @ApiResponse: uma das descrições na resposta HTTP 

@ApiResponses: a descrição geral da resposta HTTP

@ApiIgnore: Use esta anotação para ignorar esta API

@ApiError: Informações retornadas quando ocorre um erro 

@ApiImplicitParam: um parâmetro de solicitação 

@ApiImplicitParams: vários parâmetros de solicitação

Atributos @ApiImplicitParam: