springboot服务生成swagger中文接口文档

最新推荐文章于 2025-11-11 07:15:00 发布

原创最新推荐文章于 2025-11-11 07:15:00 发布 · 1.3k 阅读

0 ·

CC 4.0 BY-SA版权

swagger 专栏收录该内容

2 篇文章

订阅专栏

本文介绍如何使用Swagger自动化生成API文档，包括配置依赖包、创建Swagger配置类及通过JUnit测试类生成HTML文档的过程。

1依赖jar包引用

<pluginRepositories>
   <pluginRepository>
   <id>jcenter-snapshots</id>
   <name>jcenter</name>
   <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
   </pluginRepository>
   <pluginRepository>
   <id>jcenter-releases</id>
   <name>jcenter</name>
   <url>http://jcenter.bintray.com</url>
   <snapshots>
   <enabled>false</enabled>
   </snapshots>
   </pluginRepository>
   </pluginRepositories>

   <repositories>
   <repository>
   <id>jcentral</id>
   <name>bintray</name>
   <url>http://jcenter.bintray.com</url>
   <snapshots>
   <enabled>false</enabled>
   </snapshots>
   </repository>
   <repository>
   <id>jcenter-snapshots</id>
   <name>jcenter</name>
   <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
   </repository>
   </repositories>

<dependency>
               <groupId>io.swagger</groupId>
               <artifactId>swagger-core</artifactId>
               <version>1.5.20</version>
           </dependency
       <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <exclusions>
   <exclusion>
   <groupId>io.swagger</groupId>
   <artifactId>swagger-annotations</artifactId>
   </exclusion>
   <exclusion>
   <groupId>io.swagger</groupId>
   <artifactId>swagger-models</artifactId>
   </exclusion>
           <version>2.9.2</version>
           </dependency>
       </dependency>
       
       <dependency>
       <groupId>io.swagger</groupId>
       <artifactId>swagger-annotations</artifactId>
       <version>1.5.21</version>
       </dependency>
       <dependency>
       <groupId>io.swagger</groupId>
       <artifactId>swagger-models</artifactId>
       <version>1.5.21</version>
       </dependency>

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

然后swaggerConfig.java

package com.xxxx.server.config;

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

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.bind.annotation.RequestMethod;

import com.google.common.base.Predicates;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
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.swagger.web.DocExpansion;
import springfox.documentation.swagger.web.ModelRendering;
import springfox.documentation.swagger.web.OperationsSorter;
import springfox.documentation.swagger.web.TagsSorter;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger.web.UiConfigurationBuilder;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import springfox.documentation.service.Parameter;
import springfox.documentation.service.ResponseMessage;

@Configuration
@EnableSwagger2
@Profile({"dev","test"})
public class SwaggerConfig {
   @Bean
   public Docket createRestApi() {
       List<Parameter> operationParameters = new ArrayList<>();
       Parameter tokenParam = new ParameterBuilder()
                           .name("token")
                           .required(false)
                           .parameterType("header")
                           .modelRef(new ModelRef("string"))
                           .build();
       operationParameters.add(tokenParam);
       List<ResponseMessage> responseMessages = new ArrayList<>();
       responseMessages.add(new ResponseMessageBuilder().code(1000).message("参见200响应").build());
   return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(apiInfo())
           .useDefaultResponseMessages(false)
           .forCodeGeneration(false)
           .select()
           //为controller包路径
   .apis(RequestHandlerSelectors.basePackage("com.xxx.server.controller"))
           .paths(Predicates.not(PathSelectors.regex("/error.*")))//错误路径不监控
           .build()
           .globalOperationParameters(operationParameters)
           .globalResponseMessage(RequestMethod.GET, responseMessages)
           .globalResponseMessage(RequestMethod.POST, responseMessages);//全局参数
   }

   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               .title("xxx")
               .version("1.0")
               .contact(new Contact("MainTenance", "", null))
               .description("xxxAPI文档")
               .build();
   }

   @Bean
   UiConfiguration uiConfig() {
   return UiConfigurationBuilder.builder()
       .deepLinking(true)
       .displayOperationId(false)
       .defaultModelsExpandDepth(1)
       .defaultModelExpandDepth(1)
       .defaultModelRendering(ModelRendering.EXAMPLE)
       .displayRequestDuration(false)
       .docExpansion(DocExpansion.NONE)
       .filter(false)
       .maxDisplayedTags(null)
       .operationsSorter(OperationsSorter.ALPHA)
       .showExtensions(false)
       .tagsSorter(TagsSorter.ALPHA)
       .validatorUrl(null)
       .build();
   }
}
最后junit起动类

package com.xxx.server.swagger;

import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

import java.io.File;
import java.nio.file.Path;
import java.nio.file.Paths;

import org.asciidoctor.AsciiDocDirectoryWalker;
import org.asciidoctor.Asciidoctor;
import org.asciidoctor.AttributesBuilder;
import org.asciidoctor.OptionsBuilder;
import org.asciidoctor.SafeMode;
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.mock.web.MockHttpServletResponse;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.MvcResult;
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;

import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;

@RunWith(SpringJUnit4ClassRunner.class)
@SpringBootTest
@WebAppConfiguration
@ActiveProfiles("dev")//使用dev配置文件
public class swaggerDocumentBuilder {

   @Autowired
   private WebApplicationContext wac;

   private MockMvc mvc;

   @Before
   public void setup() {
       this.mvc = MockMvcBuilders.webAppContextSetup(this.wac).build();
   }

   @Test
   public void test() {
       String url = "/v2/api-docs";
       try {
           MvcResult mvcResult = mvc.perform(MockMvcRequestBuilders.get(url))
                                   .andExpect(status().isOk())
                                   .andReturn();
           MockHttpServletResponse response = mvcResult.getResponse();
           String swaggerJson = response.getContentAsString();
           Path outputFile = Paths.get("target/asciidoc/swagger");
           Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                   .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                   .withOutputLanguage(Language.ZH)
                   .withGeneratedExamples()
                   .withoutInlineSchema()
                   .withPathsGroupedBy(GroupBy.TAGS)
                   .build();

           Swagger2MarkupConverter.from(swaggerJson)
               .withConfig(config)
               .build()
               .toFile(outputFile);

           File outputDir = new File("target/asciidoc/");

           Asciidoctor asciidoctor = Asciidoctor.Factory.create();

           AttributesBuilder attributes = AttributesBuilder.attributes()
                   .sourceHighlighter("coderay")
                   .imagesDir("image@")
                   .attributeMissing("skip")
                   .attributeUndefined("drop-line")
                   .attribute("doctype", "book")
                   .attribute("toc",    "left")
                   .attribute("sectnums",    "true")
                   .attribute("toclevels", "3");

           OptionsBuilder options = OptionsBuilder.options()
                   .attributes(attributes)
                   .backend("html")
                   .safe(SafeMode.UNSAFE)
                   .headerFooter(true)
                   .docType("book")
                   .mkDirs(true)
                   .toDir(outputDir)
                   .destinationDir(outputDir);

           asciidoctor.convertDirectory(new AsciiDocDirectoryWalker("target/asciidoc"), options);

       } catch (Exception e) {
           e.printStackTrace();
       }
   }

}
启动junit单元测试，则在target/asciidoc目录下生成html接口文档swagger.html