springMVC整合swagger2来输出接口文档

2024-03-23 17:46:04

当前框架SpringMvc:
备注：在spring加载时应去掉config这个新增类的加载，只让springmvc加载即可：
<context:component-scan base-package=“项目包路径”>
<context:exclude-filter type=“assignable” expression=“新增的.SwaggerConfig”/>
</context:component-scan>
且需要再springmvc中加上配置：
<!-- swagger静态文件路径 -这个路径实在jar包中的，不用管即可->
<mvc:resources mapping=“swagger-ui.html” location=“classpath:/META-INF/resources/” />
<mvc:resources mapping="/webjars/**" location=“classpath:/META-INF/resources/webjars/” />
步骤：
一：准备相关jar包：

<!-- jackson-databind -->
  <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.9.5</version>
    </dependency>

    <!-- jackson-core -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-core</artifactId>
        <version>2.9.5</version>
    </dependency>

    <!-- jackson-annotations -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-annotations</artifactId>
        <version>2.9.5</version>
    </dependency>

    <dependency>
        <groupId>com.fasterxml.jackson.module</groupId>
        <artifactId>jackson-module-jaxb-annotations</artifactId>
        <version>2.9.5</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
        <exclusions>
            <exclusion>
                <artifactId>guava</artifactId>
                <groupId>com.google.guava</groupId>
            </exclusion>
        </exclusions>
    </dependency>

    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>com.google.guava</groupId>
        <artifactId>guava</artifactId>
        <version>28.0-jre</version>
    </dependency>
    <!-- https://mvnrepository.com/artifact/com.google.guava/guava -->
    <dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup</artifactId>
        <version>1.3.1</version>
    </dependency>

    <dependency>
        <groupId>org.asciidoctor</groupId>
        <artifactId>asciidoctorj-pdf</artifactId>
        <version>1.5.0-alpha.10.1</version>
        <scope>test</scope>
    </dependency>
  //  插件配置：
    <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.6</version>
            <configuration>
                <!--上一步生成的asciidoc文件路径-->
                <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                <!--HTML生成路径-->
                <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                <headerFooter>true</headerFooter>
                <doctype>book</doctype>
                <backend>html</backend>
                <sourceHighlighter>coderay</sourceHighlighter>
                <attributes>
                    <!--菜单栏在左边-->
                    <toc>left</toc>
                    <!--多标题排列-->
                    <toclevels>3</toclevels>
                    <!--自动打数字序号-->
                    <sectnums>true</sectnums>
                </attributes>
            </configuration>
        </plugin>

        <plugin>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-maven-plugin</artifactId>
            <version>1.3.1</version>
            <configuration>
                <swaggerInput>http://localhost:8083/app/v2/api-docs</swaggerInput>
                <outputDir>src/docs/asciidoc/generated</outputDir>
                <config>
                    <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                </config>
            </configuration>
        </plugin>

二：新增配置类以及方法：

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
//                .ignoredParameterTypes(query)
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))  //只显示添加@Api注解的类
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("中欧班列APP接口API")  //粗标题
                .description("中欧班列APP接口API")   //描述
                .version("2.0.1")   //api version
                .termsOfServiceUrl("http://localhost:8084/app/swagger-ui.html")
                .license("中欧班列接口文档")   //链接名称
                .licenseUrl("http://localhost:8084/app/swagger-ui.html")   //链接地址
                .build();
    }
}

第三步：在自己项目接口里加入注解
@Controller
@Api(description = “支付类”, tags=“支付标签”)

public class PayController extends BaseController {
 /**
     * 跳转到支付确认页面前校验
     * @param data orderNo  订单编号
     * @return
     */
    @ApiOperation(value = "支付校验", notes="支付校验相关参数，以及定价", httpMethod = "POST")
    @ApiImplicitParams({ @ApiImplicitParam(name = "data", value = "参数进行加密，json串{orderNo:orderNo}", dataType = "String", paramType = "query", required = true)})
    @ApiResponses({
            @ApiResponse(code=000,message="成功"),
            @ApiResponse(code=999,message="失败")
    })
    @RequestMapping("app/toPayConfirmCheck")
    @ResponseBody
    public Map<String, Object> toPayConfirmCheck(@RequestParam String data, @ApiIgnore HttpSession session) {

    }
}

此时启动项目：http://localhost:8080/name/swagger-ui.html即可看到项目接口文档（在线）

第四步：将文档导出来成xml
增加测试方法：

public class SwaggerTest {
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .withFlatBody()
                .build();
        Swagger2MarkupConverter.from(new URL("http://localhost:8084/app/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("E:\\svn\\01-代码\\trunk\\crexpress-parent\\crexpress-mobile\\src\\docs\\asciidoc\\generated\\api"));
    }
//    public void generatePDF() {
//        //样式
//        String style = "pdf-style=E:\\themes\\theme.yml";
//        //字体
//        String fontsdir = "pdf-fontsdir=E:\\fonts";
//        //需要指定adoc文件位置
//        String adocPath = "E:\\all.adoc";
        AsciidoctorInvoker.main(new String[]{"-a",style,"-a",fontsdir,"-b","pdf",adocPath});
//    }

    pubic static void main(String[] args) {
        SwaggerTest test = new SwaggerTest();
        try {
            test.generateAsciiDocs();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

此时就会在
E:\svn\01-代码\trunk\crexpress-parent\crexpress-mobile\src\docs\asciidoc\generated\api这个路径下生成api.adoc文件。
然后

命令行：asciidoctor:process-asciidoc
然后待生成api.adoc文件后执行此maven就可以生成静态html接口文档了。

swagger2 注解整体说明
复制代码
@Api：用在请求的类上，表示对类的说明
tags=“说明该类的作用，可以在UI界面上看到的注解”
value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”

@ApiOperation：用在请求的方法上，说明方法的用途、作用
value=“说明方法的用途、作用”
notes=“方法的备注说明”

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）–> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType=“Integer”
defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性
复制代码

@Api：用在请求的类上，说明该类的作用

@Api：用在请求的类上，说明该类的作用
tags=“说明该类的作用”
value=“该参数没什么意义，所以不需要配置”
示例
@Api(tags=“APP用户注册Controller”)

@ApiOperation：用在请求的方法上，说明方法的作用

@ApiOperation：“用在请求的方法上，说明方法的作用”
value=“说明方法的作用”
notes=“方法的备注说明”
示例
@ApiOperation(value=“用户注册”,notes=“手机号、密码都是必输项，年龄随边填，但必须是数字”)

@ApiImplicitParams：用在请求的方法上，包含一组参数说明

复制代码
@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）–> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType=“Integer”
defaultValue：参数的默认值
复制代码

示例

@ApiImplicitParams({
@ApiImplicitParam(name=“mobile”,value=“手机号”,required=true,paramType=“form”),
@ApiImplicitParam(name=“password”,value=“密码”,required=true,paramType=“form”),
@ApiImplicitParam(name=“age”,value=“年龄”,required=true,paramType=“form”,dataType=“Integer”)
})
4. @ApiResponses：用于请求的方法上，表示一组响应

@ApiResponses：用于请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类

示例

@ApiOperation(value = “select1请求”,notes = “多个参数，多种的查询参数类型”)
@ApiResponses({
@ApiResponse(code=400,message=“请求参数没填好”),
@ApiResponse(code=404,message=“请求路径没有或页面跳转路径不对”)
})
5. @ApiModel：用于响应类上，表示一个返回响应数据的信息
ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性
示例

复制代码
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.io.Serializable;

@ApiModel(description= “返回响应数据”)
public class RestMessage implements Serializable{

@ApiModelProperty(value = "是否成功")
private boolean success=true;
@ApiModelProperty(value = "返回对象")
private Object data;
@ApiModelProperty(value = "错误编号")
private Integer errCode;
@ApiModelProperty(value = "错误信息")
private String message;

/* getter/setter */

}

码农公寓

相关文章