springboot集成swagger

最新推荐文章于 2023-09-07 12:48:03 发布

斗码士

最新推荐文章于 2023-09-07 12:48:03 发布

阅读量532

点赞数 1

分类专栏： Spring boot 2.x入门到深入文章标签： swagger springboot 源码 api 集成

本文链接：https://blog.csdn.net/qq_14926283/article/details/109840976

版权

Spring boot 2.x入门到深入专栏收录该内容

32 篇文章 1 订阅

订阅专栏

开发工程中后端是比较苦哈哈的，经常要考虑各种复杂的逻辑，出现bug又要经常修改，对应出现api接口也要经常修改的问题

前后端分离，安卓ios端，vue端

编写及维护接口文档会耗费不少精力，经常来不及更新。

这时候老板就开始骂了，这个功能怎么会出现bug？

前端推锅:“后端api给错了，我们按他们给的文档来调的，鬼知道接口变更了”

后端:“老板说了我们这个需求要变更，让你们修改个入参，你们当时没时间改，后来忘了怪我？”

然后就互相约架，放学后别走，操场见

终于swagger在千呼万唤中出来了:“都住手，api这种小事交给我来解决”

Swagger 是一套围绕 Open API 规范构建的开源工具，可以帮助设计，构建，记录和使用 REST API。

　　Swagger 工具包括的组件：

　　　　Swagger Editor ：基于浏览器编辑器，可以在里面编写 Open API规范。类似 Markdown 具有实时预览描述文件的功能。

　　　　Swagger UI：将 Open API 规范呈现为交互式 API 文档。用可视化UI 展示描述文件。

　　　　Swagger Codegen：将 OpenAPI 规范生成为服务器存根和客户端库。通过 Swagger Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。

　　　　Swagger Inspector：和 Swagger UI 有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。

　　　　Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到 Swagger Hub 中。在 Swagger Hub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

　　　　使用 Swagger，就是把相关的信息存储在它定义的描述文件里面（yml 或 json 格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

好了废话不多说了，干活

pom.xml

<?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 https://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>2.3.0.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.zkb</groupId>
    <artifactId>spring-boot-swagger-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>spring-boot-swagger-demo</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.22</version>
        </dependency>

        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>
        <!-- swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.1</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>1.5.14.RELEASE</version>
                <dependencies>
                    <!--springloaded hot deploy -->
                    <dependency>
                        <groupId>org.springframework</groupId>
                        <artifactId>springloaded</artifactId>
                        <version>1.2.4.RELEASE</version>
                    </dependency>
                </dependencies>
                <executions>
                    <execution>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <layout>ZIP</layout>
                    <mainClass>com.zkb.SpringBootSwaggerDemoApplication</mainClass>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

application.properties

server.port=9999

package com.zkb;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@SpringBootApplication
public class SpringBootSwaggerDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringBootSwaggerDemoApplication.class, args);
    }

}

package com.zkb.config;

import io.swagger.annotations.ApiOperation;
import io.swagger.models.auth.In;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.Contact;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.Arrays;
import java.util.List;


@Configuration
@EnableSwagger2
public class SwaggerApp {



    @Bean
    public Docket createRestApi1() {
        return new Docket(DocumentationType.SWAGGER_2).enable(true).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .apis(RequestHandlerSelectors.basePackage("com.zkb.controller"))
                .paths(PathSelectors.any()).build().securitySchemes(apiKeyList()).groupName("接口中心");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API")
                .contact(new Contact("XXXXX", "http://XXXXXX.XXXX/", ""))
                .version("1.0")
                .description("API 描述")
                .build();
    }

    private List<ApiKey> apiKeyList() {
        return Arrays.asList(new ApiKey("登录token", "token", In.HEADER.name()),
                new ApiKey("设备类型(android,ios,pc)---必填", "deviceType", In.HEADER.name()));
    }
}

package com.zkb.controller;


import com.zkb.vo.User;
import com.zkb.vo.UserFo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

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

/**
 * @author jinbin
 * @date 2018-07-08 20:45
 */
@Controller
@RequestMapping("/user")
@Api(value = "user",tags = "user")
public class UserController {

    private static final Map<String,User> userHashMap = new HashMap<String,User>();


    static {
        User user1 = new User("a","a","123456");
        User user2 = new User("b","a","123456");
        User user3 = new User("c","a","123456");
        User user4 = new User("d","a","123456");
        userHashMap.put(user1.getUsername(),user1);
        userHashMap.put(user2.getUsername(),user2);
        userHashMap.put(user3.getUsername(),user3);
        userHashMap.put(user4.getUsername(),user4);
    }

    //登录
    @PostMapping("/login")
    @ApiOperation(value="登录",notes = "登录")
    @ResponseBody
    public String login(@RequestBody UserFo userFo){
        User user = userHashMap.get(userFo.getUsername());
        if (userFo.getPassword().equals(user.getPassword())) {
            return "成功";
        }else{
            return "失败";
        }
    }
}

package com.zkb.vo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.ToString;
import lombok.experimental.Accessors;

import java.io.Serializable;

/**
 * <h3>spring-boot-swagger-demo</h3>
 * <p></p>
 *
 * @author : zkb
 * @date : 2020-11-19 17:45
 **/

@Data
@NoArgsConstructor
@AllArgsConstructor
@Accessors(chain = true)
@ToString
@ApiModel(value = "用户信息", description = "用户信息")
public class User implements Serializable {

    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "密码")
    private String password;

    @ApiModelProperty(value = "电话号码")
    private String telphone;
}

package com.zkb.vo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.ToString;
import lombok.experimental.Accessors;

import java.io.Serializable;

/**
 * <h3>spring-boot-swagger-demo</h3>
 * <p></p>
 *
 * @author : zkb
 * @date : 2020-11-19 18:11
 **/

@Data
@NoArgsConstructor
@AllArgsConstructor
@Accessors(chain = true)
@ToString
@ApiModel(value = "用户登录", description = "用户登录")
public class UserFo implements Serializable {

    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "密码")
    private String password;
}

结构如上图

也就是我们之前有设置的请求头里面的自定义参数了

demo自取https://download.csdn.net/download/qq_14926283/13129317

斗码士

关注

1
点赞
踩
1

收藏

觉得还不错? 一键收藏
打赏
0
评论
springboot集成swagger

开发工程中后端是比较苦哈哈的，经常要考虑各种复杂的逻辑，出现bug又要经常修改，对应出现api接口也要经常修改的问题前后端分离，安卓ios端，vue端编写及维护接口文档会耗费不少精力，经常来不及更新。这时候老板就开始骂了，这个功能怎么会出现bug？前端推锅:“后端api给错了，我们按他们给的文档来调的，鬼知道接口变更了”后端:“老板说了我们这个需求要变更，让你们修改个入参，你们当时没时间改，后来忘了怪我？”然后就互相约架，放学后别走，操场见 ...
复制链接

扫一扫