SpringBoot+SpringSecurity下自动生成Swagger接口文档

墨蓝 2021-11-29 16:46 609阅读 0赞

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQyMTA5NzQ2_size_16_color_FFFFFF_t_70][]

### 1.什么是Swagger？ ###

OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上。

Swagger是符合OpenAPI规范的接口开发工具，支持从设计和文档到测试和部署的整个API生命周 期的开发。 (https://swagger.io/)

### 2.Swagger常用注解 ###

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

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

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

@ApiParam：单个参数描述

@ApiModel：用对象来接收参数

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

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

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

@ApiImplicitParam：一个请求参数

@ApiImplicitParams：多个请求参数

### 3.Swagger生成接口文档的工作原理 ###

1、系统启动，扫描到api工程中的Swagger2Confifiguration类

2、在此类中指定了包路径com.xuecheng，找到在此包下及子包下标记有@RestController注解的controller类

3、根据controller类中的Swagger注解生成接口文档。

### 4.配置完整依赖 ###

<?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>
        <parent>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-parent</artifactId>
            <version>1.5.21.RELEASE</version>
            <relativePath/> 
        </parent>
        <groupId>com.chen</groupId>
        <artifactId>springsecuritytest</artifactId>
        <version>0.0.1-SNAPSHOT</version>
        <name>springsecuritytest</name>
        <description>Demo project for Spring Boot</description>
    
        <properties>
            <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
            <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
            <java.version>1.8</java.version>
        </properties>
    
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-data-redis</artifactId>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-security</artifactId>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </dependency>
            <dependency>
                <groupId>org.mybatis.spring.boot</groupId>
                <artifactId>mybatis-spring-boot-starter</artifactId>
                <version>1.3.4</version>
            </dependency>
            <dependency>
                <groupId>org.springframework.session</groupId>
                <artifactId>spring-session</artifactId>
            </dependency>
            <dependency>
                <groupId>mysql</groupId>
                <artifactId>mysql-connector-java</artifactId>
                <scope>runtime</scope>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-test</artifactId>
                <scope>test</scope>
            </dependency>
            <dependency>
                <groupId>org.springframework.security</groupId>
                <artifactId>spring-security-test</artifactId>
                <scope>test</scope>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-aop</artifactId>
            </dependency>
            
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.7.0</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.7.0</version>
            </dependency>
    
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
            </dependency>
    
        </dependencies>
    
        <build>
            <plugins>
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                </plugin>
            </plugins>
        </build>
    
    </project>

### 5.编写Swagger配置类 ###

package com.chen.config;
    
    import io.swagger.annotations.ApiOperation;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
    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.service.Contact;
    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 extends WebMvcConfigurerAdapter {
    
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
    
            registry.addResourceHandler("swagger-ui.html")
                    .addResourceLocations("classpath:/META-INF/resources/");
    
            registry.addResourceHandler("/webjars/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    //加了ApiOperation注解的类，才生成接口文档
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    //包下的类，才生成接口文档
                    //.apis(RequestHandlerSelectors.basePackage("com.chen.controller"))
                    .paths(PathSelectors.any())
                    .build()
                    .securitySchemes(security());
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("文档标题") //文档标题
                    .description("") //接口文档描述
                    .termsOfServiceUrl("https://www.baidu.com") //服务器
                    .version("1.0.0") //版本
                    .contact(new Contact("柠檬不酸", "", "15218979950@163.com"))//作者信息
                    .build();
        }
    
        private List<ApiKey> security() {
            return newArrayList(
                    new ApiKey("token", "token", "header")
            );
        }
    
    }

### 6.编写SpringSecurity配置类 ###

package com.chen.config;
    
    import org.springframework.context.annotation.Configuration;
    import org.springframework.security.config.annotation.web.builders.HttpSecurity;
    import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
    
    @Configuration
    public class BrowerSecurityConfig extends WebSecurityConfigurerAdapter {
    
        @Override
        protected void configure(HttpSecurity http) throws Exception {
            http.formLogin()          // 定义当需要用户登录时候，转到的登录页面。
                    .and()
                    .authorizeRequests()    // 定义哪些URL需要被保护、哪些不需要被保护
                    .anyRequest()        // 任何请求,登录后可以访问
                    .authenticated();
    
            http.authorizeRequests()
                    .antMatchers("/v2/api-docs",//swagger api json
                            "/swagger-resources/configuration/ui",//用来获取支持的动作
                            "/swagger-resources",//用来获取api-docs的URI
                            "/swagger-resources/configuration/security",//安全选项
                            "/swagger-ui.html",
                            "/webjars/**").permitAll();
        }
    }

### 7.编写Controller进行测试 ###

package com.chen.controller;
    
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    @RestController
    @Api(value = "测试用的controller")
    public class HelloController {
    
        @ApiOperation(value = "接口名称", notes = "接口描述")
        @GetMapping("/hello")
        public String hello(String name){
            return "hello";
        }
    
    
    }

### 8.查看显示效果 ###

在浏览器输入 [http://localhost/security/swagger-ui.html\#/][http_localhost_security_swagger-ui.html]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQyMTA5NzQ2_size_16_color_FFFFFF_t_70 1][]

使用swagger既可以让后端开发人员进行接口的调试，又给前端开发人员定义了一个开发文档，对后端人员来说是一个好东西。

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQyMTA5NzQ2_size_16_color_FFFFFF_t_70]: /images/20211129/d7aa2d0ae52246698e6cf5de193a0440.png
[http_localhost_security_swagger-ui.html]: http://localhost/security/swagger-ui.html#/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQyMTA5NzQ2_size_16_color_FFFFFF_t_70 1]: /images/20211129/8ff93cbc00bf4512ac5426c8a5c2c370.png