java boot 多模块使用swagger2 并且生成接口文档(word)

不知道叫啥丫

已于 2023-03-02 10:22:28 修改

阅读量963

点赞数

分类专栏： sgagger2 java 文章标签： java Powered by 金山文档

于 2023-02-25 15:49:38 首次发布

本文链接：https://blog.csdn.net/si99999/article/details/129215255

版权

java 同时被 2 个专栏收录

14 篇文章 0 订阅

订阅专栏

sgagger2

3 篇文章 0 订阅

订阅专栏

导出来的word截图，需要的都有

只需要把swagger2生成的json转换即可
地址:https://tools.kalvinbg.cn/dev/swagger2word
示例json:

{"swagger":"2.0","info":{"description":"简单优雅的 restfun 风格 ","version":"1.0","title":"SpringBoot使用Swagger构建api文档","termsOfService":"00----"},"host":"localhost:8080","basePath":"/","tags":[{"name":"user-controller","description":"User Controller"}],"paths":{"/tt":{"get":{"tags":["user-controller"],"summary":"用户接口","description":"通过id查询用户","operationId":"getUserUsingGET","produces":["*/*"],"parameters":[{"name":"id","in":"query","description":"用户id","required":true,"type":"string"},{"name":"token","in":"header","description":"token令牌","required":false,"type":"string"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/User"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}},"/tt2":{"get":{"tags":["user-controller"],"summary":"用户接口","description":"通过用户查询用户","operationId":"getUser2UsingGET","produces":["*/*"],"parameters":[{"name":"id","in":"query","description":"用户id","required":true,"type":"string"},{"name":"name","in":"query","description":"用户name","required":true,"type":"string"},{"name":"token","in":"header","description":"token令牌","required":false,"type":"string"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/User"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}},"/tt3":{"post":{"tags":["user-controller"],"summary":"用户接口","description":"通过用户查询用户","operationId":"getUser3UsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"name":"token","in":"header","description":"token令牌","required":false,"type":"string"},{"in":"body","name":"user2","description":"user实体","required":true,"schema":{"$ref":"#/definitions/User"}}],"responses":{"200":{"description":"角色信息","schema":{"$ref":"#/definitions/role"}},"201":{"description":"Created"},"400":{"description":"请求参数错误"},"401":{"description":"未授权"},"403":{"description":"Forbidden"},"404":{"description":"用户不存在"},"500":{"description":"服务器内部错误"}},"deprecated":false}},"/tt4":{"post":{"tags":["user-controller"],"summary":"用户接口","description":"通过用户查询用户","operationId":"getUser4UsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"name":"token","in":"header","description":"token令牌","required":false,"type":"string"},{"in":"body","name":"user2","description":"user实体","required":true,"schema":{"$ref":"#/definitions/User"}}],"responses":{"200":{"description":"OK","schema":{"type":"string"}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}},"/user/{userId}":{"get":{"tags":["user-controller"],"summary":"获取用户信息","description":"根据用户ID获取用户信息","operationId":"getUserInfoUsingGET","produces":["*/*"],"parameters":[{"name":"token","in":"header","description":"token令牌","required":false,"type":"string"},{"name":"userId","in":"path","description":"userId","required":true,"type":"integer","format":"int64"}],"responses":{"200":{"description":"用户id","schema":{"type":"string"}},"400":{"description":"请求参数错误"},"401":{"description":"未授权"},"403":{"description":"Forbidden"},"404":{"description":"用户不存在"},"500":{"description":"服务器内部错误"}},"deprecated":false}}},"definitions":{"User":{"type":"object","required":["id"],"properties":{"id":{"type":"string","example":123,"description":"用户id"},"name":{"type":"string","example":"张三","description":"用户名"},"sex":{"type":"string","example":"男","description":"性别"}},"title":"User"},"role":{"type":"object","properties":{"dtai":{"description":"部门","$ref":"#/definitions/部门"},"name":{"type":"string","example":88989,"description":"角色id"}},"title":"role"},"部门":{"type":"object","properties":{"age":{"type":"string","example":27,"description":"部门年龄"}},"title":"部门"}}}

实现方法：

创建一个子模块 swg 模块
导入swagger2 pom 依赖坐标


//其他依赖
 <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
 </dependency>
 <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
  </dependency>
//swg依赖
 <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>

单个controller 配置文件

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

/**
 * @author User
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 需要扫描的cntroller 
                .apis(RequestHandlerSelectors.basePackage("com.example.sub.controller"))
                .paths(PathSelectors.any())
                .build().globalOperationParameters(this.getParameterList());
    }

    private ApiInfo apiInfo() {
        //这些其实没啥用
        return new ApiInfoBuilder()
                .title("SpringBoot使用Swagger构建api文档")
                .description("简单优雅的 restfun 风格 ")
                .termsOfServiceUrl("00----")
                .version("1.0")
                .build();
    }

    /**
     * 添加head参数配置
     */
    private List<Parameter> getParameterList() {
        ParameterBuilder clientIdTicket = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        // name 是传入的token名字token 
        clientIdTicket.name("token").description("token令牌")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false).build(); //设置false，表示clientId参数 非必填,可传可不传！
        pars.add(clientIdTicket.build());

        return pars;

    }

}
多个controlelr 配置文件
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

/**
 * @author User
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi1() {

        return new Docket(DocumentationType.SWAGGER_2)
                // 可以选择的名字
                .groupName("fs")
                .apiInfo(apiInfo())
                .select()
                // 需要扫描的cntroller 
                .apis(RequestHandlerSelectors.basePackage("com.yssoo.modules.storage.controller"))
                .paths(PathSelectors.any())

                .build().globalOperationParameters(this.getParameterList());
    }

    @Bean
    public Docket createRestApi2() {

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("swg")
                .apiInfo(apiInfo())
                .select()
                // 需要扫描的cntroller 
                .apis(RequestHandlerSelectors.basePackage("com.yssoo.lims.modules.swagger.controller"))
                .paths(PathSelectors.any())

                .build().globalOperationParameters(this.getParameterList());
    }

    private ApiInfo apiInfo() {
        //这些其实没啥用
        return new ApiInfoBuilder()
                .title("SpringBoot使用Swagger构建api文档")
                .description("简单优雅的 restfun 风格 ")
                .termsOfServiceUrl("00----")
                .version("1.0")
                .build();
    }

    /**
     * 添加head参数配置
     */
    private List<Parameter> getParameterList() {
        ParameterBuilder clientIdTicket = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        // name 是传入的token名字token
        clientIdTicket.name("X-Access-Token").description("token令牌")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false).build(); //设置false，表示clientId参数 非必填,可传可不传！
        pars.add(clientIdTicket.build());

        return pars;

    }

}

这里可以选不同的controller包

创建需要使用到他的子模块(user)，然后依赖swg子模块
 <dependencies>
        <dependency>
            <artifactId>swg</artifactId>
            <groupId>org.example</groupId>
            <version>1.0-SNAPSHOT</version>
        </dependency>
</dependencies>

在user块中书写controller

import com.example.sub.entity.Role;
import com.example.sub.entity.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

/**
 * @author :si
 * @date :2023/2/24
 */
@RestController
//控制层藐视
@Api("用户控制层")
public class UserController {

    //value :接口描述 notes:详细解释
    @ApiOperation(value = "用户接口",notes = "通过id查询用户")
    @GetMapping("/tt")
    // name：参数值，value：参数描述   required ：是否必填  dataType ：参数类型
    @ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "string")

    public User getUser(@RequestParam("id") String id){

        User user = new User();
        user.setId(id);
        user.setName("123");
        user.setSex("男");
        return  user;

    }


    //value :接口描述 notes:详细解释
    @ApiOperation(value = "用户接口",notes = "通过用户查询用户")
    @GetMapping("/tt2")
    // ApiImplicitParams对个参数，嵌套即可中间使用{}  逗号分割
    // name：参数值，value：参数描述   required ：是否必填  dataType ：参数类型
    @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "string"),
            @ApiImplicitParam(name = "name",value = "用户name",required = true,dataType = "string")})

    public User getUser2(@RequestParam("id") String id,@RequestParam("name") String name){

        User user = new User();
        user.setId(id);
        user.setName("123");
        user.setSex("男");
        return  user;

    }

    //value :接口描述 notes:详细解释
    @ApiOperation(value = "用户接口",notes = "通过用户查询用户")
    @PostMapping("/tt3")
    // ApiImplicitParams对个参数，嵌套即可中间使用{}  逗号分割
    // name：参数值，value：参数描述   required ：是否必填  dataType ：参数类型
    //注：如果参数是实体类，那么dataType 需要和实体类中的 @ApiModel("User") 名字一致
    @ApiImplicitParams(@ApiImplicitParam(name = "user2", value = "user实体", required = true, dataType = "User"
    ))
    // ApiResponses 可以描述返回值信息
    @ApiResponses({
            @ApiResponse(code = 200, message = "角色信息", response = Role.class),
            @ApiResponse(code = 400, message = "请求参数错误"),
            @ApiResponse(code = 401, message = "未授权"),
            @ApiResponse(code = 404, message = "用户不存在"),
            @ApiResponse(code = 500, message = "服务器内部错误")
    })
    public Role getUser3(@RequestBody User user2){

        Role role = new Role();
        role.setName("1");

        return  role;

    }


    //value :接口描述 notes:详细解释
    @ApiOperation(value = "用户接口",notes = "通过用户查询用户")
    @PostMapping("/tt4")
    // ApiImplicitParams对个参数，嵌套即可中间使用{}  逗号分割
    // name：参数值，value：参数描述   required ：是否必填  dataType ：参数类型
    //注：如果参数是实体类，那么dataType 需要和实体类中的 @ApiModel("User") 名字一致
    @ApiImplicitParams(@ApiImplicitParam(name = "user2", value = "user实体", required = true, dataType = "User"
    ))
   // ApiResponse 如果返回的是一个string类中这种，可以在message中描述
    @ApiResponse(code = 200, message = "返回成功修改的名字",response = String.class)
    public String getUser4(@RequestBody User user2){

        User user = new User();
        user.setId("1");
        user.setName("123");
        user.setSex("男");
        return  "ok";

    }

    @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
    @ApiResponses({
            @ApiResponse(code = 200, message = "用户id", response = String.class),
            @ApiResponse(code = 400, message = "请求参数错误"),
            @ApiResponse(code = 401, message = "未授权"),
            @ApiResponse(code = 404, message = "用户不存在"),
            @ApiResponse(code = 500, message = "服务器内部错误")
    })
    @GetMapping("/user/{userId}")
    public String getUserInfo(@PathVariable Long userId) {
        // 获取用户信息的业务逻辑
        return "User Info";
    }

}

user实体类

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

/**
 * @author :si
 * @date :2023/2/24
 */
@Data
//实体类的描述
@ApiModel("User")
public class User {
    // 这个注解可以在接口文档中展示这字段的描述
    @ApiModelProperty(value = "用户id",example = "123")
    private String id;

    @ApiModelProperty(  value = "用户名",example = "张三")
    private String name;

    @ApiModelProperty( value = "性别",example = "男")
    private String sex;
}

role实体
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * @author :si
 * @date :2023/2/25
 */
@Data
@ApiModel("role")
public class Role {
    @ApiModelProperty(value = "角色id",example = "88989")
    private String name;
    @ApiModelProperty(value = "部门")
    private dtai dtai;
    @ApiModel("部门")
    @Data
    class dtai{
        @ApiModelProperty(value = "部门年龄",example = "27")
        private String age;
    }
}

swagger2访问地址：http://host:port/context-path/swagger-ui.html
有些同学可能在yml文件中加了context-path 必须加上

不加就是：http://localhost:8080/swagger-ui.html
加了就是：http://localhost:8080/lims/swagger-ui.html

获取json的地址，就在swagger2 的页面上

不知道叫啥丫

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
java boot 多模块使用swagger2 并且生成接口文档(word)

sgw2生成的json，转出word接口文档
复制链接

扫一扫

专栏目录

java boot 多模块使用swagger2 并且生成接口文档(word)

“相关推荐”对你有帮助么？