1. 軟件依賴

Spring Boot

Swagger2

Swagger2markup

asciidoctor-maven-plugin

2. SpringBoot配置Swagger2

2.1 引入Swagger2相關(guān)依賴

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-staticdocs</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>

2.1 編寫(xiě)SwaggerConfig配置類

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.xxx.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文檔")
                .description("API使用說(shuō)明")
                .termsOfServiceUrl("http://localhost:8088")
                .version("1.0")
                .build();
    }
}

@SpringBootApplication
@EnableSwagger2
public class MyApplication {

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

2.2 在controller的方法上添加swagger注解

    @ApiOperation(value = "刪除指定ID標(biāo)記")
    @ApiImplicitParam(name = "id", value = "標(biāo)記ID", required = true, dataType = "string")
    @RequestMapping(value = "/mark/{id}", method = RequestMethod.DELETE)
    public void delete(@PathVariable String id) {
        markService.delete(id);
    }
    
    @ApiOperation(value = "查詢指定ID標(biāo)記")
    @ApiImplicitParam(name = "id", value = "標(biāo)記ID", required = true, dataType = "string")
    @RequestMapping(value = "/mark/{id}", method = RequestMethod.GET)
    public TblMark getById(@PathVariable String id) {
        return markService.getById(id);
    }
    
    @ApiOperation(value = "更新指定ID標(biāo)記")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "標(biāo)記ID", required = true, dataType = "string"),
        @ApiImplicitParam(name = "mark", value = "標(biāo)記實(shí)體TblMark", required = true, dataType = "TblMark")
    })
    @RequestMapping(value = "/mark/{id}", method = RequestMethod.PUT)
    public TblMark update(@PathVariable String id,@RequestBody TblMark mark) {
        return markService.update(id, mark);
    }

3. 編寫(xiě)測(cè)試類生成asciidoc

    @Test
    public void generateAsciiDocs() throws MalformedURLException {
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder().withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();
        Swagger2MarkupConverter.from(new URL("http://localhost:8088/v2/api-docs")).withConfig(config).build()
                .toFile(Paths.get("src/docs/asciidoc/generated/all"));
    }

3. 使用asciidoctor-maven-plugin生成HTML文檔

3.1 配置asciidoctor-maven-plugin插件

3.1.1 添加插件倉(cāng)庫(kù)

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

3.1.2 配置插件的sourceDirectory屬性為asciidoc文檔地址

                <plugin>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-maven-plugin</artifactId>
                    <version>${asciidoctor.maven.plugin.version}</version>
                    <dependencies>
                        <!-- Comment this section to use the default jruby artifact provided 
                            by the plugin -->
                        <dependency>
                            <groupId>org.jruby</groupId>
                            <artifactId>jruby-complete</artifactId>
                            <version>${jruby.version}</version>
                        </dependency>
                        <!-- Comment this section to use the default AsciidoctorJ artifact 
                            provided by the plugin -->
                        <dependency>
                            <groupId>org.asciidoctor</groupId>
                            <artifactId>asciidoctorj</artifactId>
                            <version>${asciidoctorj.version}</version>
                        </dependency>
                    </dependencies>
                    <configuration>
                        <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                        <attributes>
                            <endpoint-url>http://example.org</endpoint-url>
                            <sourcedir>${project.build.sourceDirectory}</sourcedir>
                            <project-version>${project.version}</project-version>
                        </attributes>
                    </configuration>
                    <executions>
                        <execution>
                            <id>asciidoc-to-html</id>
                            <phase>generate-resources</phase>
                            <goals>
                                <goal>process-asciidoc</goal>
                            </goals>
                            <configuration>
                                <backend>html5</backend>
                                <sourceHighlighter>coderay</sourceHighlighter>
                                <attributes>
                                    <imagesdir>./images</imagesdir>
                                    <toc>left</toc>
                                    <icons>font</icons>
                                    <sectanchors>true</sectanchors>
                                    <idprefix />
                                    <idseparator>-</idseparator>
                                    <docinfo1>true</docinfo1>
                                </attributes>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>

4. 生成文檔

4.1 運(yùn)行asciidoc測(cè)試類

4.2 運(yùn)行mvn generate-resources朱转，在target/generated-docs下生成html文檔

5.注意

5.1 POM文件中的<pluginManagement>標(biāo)簽會(huì)讓其中的插件不執(zhí)行，導(dǎo)致錯(cuò)誤

5.2 <execution>標(biāo)簽的錯(cuò)誤可在eclipse中選擇quickFix诱鞠，進(jìn)行忽略