spring boot 集成Swagger 2

目录

spring boot 集成Swagger2

1:项目结构

2：pom.xml添加 maven 依赖

3：创建SwaggerConfig.java

4：Model--User的实体类position相同

5：API接口编写-- User请求Position相同

6：启动Spring Boot 应用

7：数据类型返回

---

---

Swagger 2 是一个规范和完整的文档框架，它可以用于生成，描述，调用和可视化 RESTful 风格的 Web 服务.

spring boot 集成Swagger2

1:项目结构

●  SwaggerConfig 是将swagger2 开启并注入到spring中。用于更改Swagger2 的参数与用法 。

2：pom.xml添加 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>

3：创建SwaggerConfig.java

package com.jzx.swagger.dome.config;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
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.ArrayList;


@Configuration    //用于构建bean定义以及初始化Spring容器。
@EnableSwagger2   //开启Swagger2
public class SwaggerConfig {

    @Bean
    public Docket  docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("职位模块")
                .enable(true)  //配置是否启用Swagger，false游览器无法访问
                .select()  //通过select去配置扫描接口
                //RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.jzx.swagger.dome"))
                //通过path来过滤，扫描以"/position"开头的接口
                .paths(PathSelectors.ant("/position/*"))
                .build();
    }

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("用户模块")
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jzx.swagger.dome"))
                .paths(PathSelectors.ant("/user/*"))
                .build();
    }

    private ApiInfo apiInfo(){

        Contact contact = new Contact("金正鑫", "http://localhost:8080/swagger-ui.html#/", "jinzhengxin2019@163.com");
        return new ApiInfo(
               "Swagger2 练习文档",    //标题
               "金正鑫",         //作者姓名
               "1.0",              //版本
               "http://localhost:8080/swagger-ui.html#/",
                contact,
               "Apache 2.0",
               "http://www.apache.org/licenses/LICENSE-2.0",
               new ArrayList());
    }
}

●  @configuration ：让spring加载该配置类

●  @EnableSwagger2 ：启用Swagger2 

●  创建Docket的 @Bean ，应用Docket方法来配置Swagger2 ，上述代码创建了两个@Bean （职位模块和用户模块），这样在页面文档将有两个模块，每个模块只显示对应的请求。

4：Model--User的实体类position相同

package com.jzx.swagger.dome.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String passwrod;


    public User() {
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPasswrod() {
        return passwrod;
    }

    public void setPasswrod(String passwrod) {
        this.passwrod = passwrod;
    }
}

 添加下面两个注解会在Swagger2的页面中会显示这个模块所使用的实体类和实体类参数的意义。

●  @ApiModel () ：描述是什么实体类

●  @ApiModelProperty() ：描述实体类参数的意义

5：API接口编写-- User请求Position相同

package com.jzx.swagger.dome.controller;


import com.jzx.swagger.dome.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(description = "用户管理")
@RestController
public class UserSwaggerController {


    @GetMapping("/user/message")
    @ApiOperation(value = "返回用户信息",response = User.class ,notes = "用户")
    @ApiImplicitParam(name = "user",value = "用户",dataType = "User")
    public User user( User user){
        return user;
    }

    @GetMapping("/user/username")
    @ApiOperation(value = "返回用户名",response = User.class,notes = "用户名")
    public String user1(@ApiParam(value = "用户名",required = true,name = "用户名") String username){
        return username;
    }
}

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

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

●  @ApiParam（）：单个参数描述

●  @ApiImplicitParam（）：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值

6：启动Spring Boot 应用

用户模块

 

 职位模块

7：数据类型返回

                                                             ●  controlller

●MODEL

 

 ●Swagger2 页面